IBM® WebSphere, 


Using WebSphere Message 
Broker V8 in 

Mid-Market Environments 


Develop and access Windows 



Communication Foundation services 


Integrate .NET applications 


Integrate managed 
file transfer 


Vinicius D. G. Braganga 
Minsung Byun 
David Crighton 
Kiran Darbha 
Jefferson Lowrey 
Pavel Malyutin 
Abhinav Priyadarshi 
Rashmi Katagall 
Carla Sadtler 


Redbooks 


ibm.com/redbooks 



International Technical Support Organization 


Using WebSphere Message Broker V8 in Mid-Market 
Environments 

August 2012 


SG24-8020-00 



Note: Before using this information and the product it supports, read the information in “Notices” on 
page xi. 


First Edition (August 2012) 


© Copyright International Business Machines Corporation 2012. All rights reserved. 

Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule 
Contract with IBM Corp. 




Contact an IBM Software Services Sales Specialist 



Start SMALL, Start BIG, ...JUST START 

architectural knowledge, skills, research and development . . . 

that's IBM Software Services for WebSphere. 

Our highly skilled consultants make it easy for you to design, build, test and deploy solutions, helping 
you build a smarter and more efficient business. Our worldwide network of services specialists wants you 
to have it all! Implementation, migration, architecture and design services: IBM Software Services has 
the right fit for you. We also deliver just-in-time, customized workshops and education tailored for your 
business needs. You have the knowledge, now reach out to the experts who can help you extend and 
realize the value. 

For a WebSphere services solution that fits your needs, contact an IBM Software Services Sales Specialist: 
ibm.com/developerworks/websphere/services/contacts.html 


Contact an IBM Software Services Sales Specialist iii 



Using WebSphere Message Broker V8 in Mid-Market Environments 



Contents 


Contact an IBM Software Services Sales Specialist iii 

Notices xi 

Trademarks xii 

Preface xiii 

The team who wrote this book xiii 

Now you can become a published author, too! xv 

Comments welcome xvi 

Stay connected to IBM Redbooks xvi 

Chapter 1. WebSphere Message Broker for mid-market solutions 1 

1.1 WebSphere Message Broker 2 

1.1.1 Message processing 2 

1.1.2 Connectivity options 4 

1.1.3 WebSphere Message Broker editions 6 

1.2 WebSphere Message Broker for midmarket 7 

1.2.1 Microsoft .Net integration 7 

1 .2.2 File processing and transfer 8 

1 .3 Additional resources 8 

Chapter 2. Introduction to WebSphere Message Broker V8 9 

2.1 Runtime architecture of WebSphere Message Broker 10 

2.1.1 Broker 10 

2.1.2 Execution groups 10 

2.2 Development environment of WebSphere Message Broker 11 

2.2.1 WebSphere Message Broker Toolkit 11 

2.2.2 Applications and libraries 12 

2.2.3 Message flows 13 

2.2.4 Message 15 

2.2.5 Message modeling 15 

2.2.6 Pattern instances 17 

2.2.7 Microsoft Visual Studio 2010 integration 18 

2.3 Connectivity options 18 

2.3.1 WebSphere MQ 18 

2.3.2 Java Message Service (JMS) 1.1 19 

2.3.3 WebSphere MQ/JMS 20 

2.3.4 SOAP-based web services 21 

2.3.5 HTTP and HTTPS 22 

2.3.6 File 23 

2.3.7 Java Connector Architecture (JCA) Adapters and WebSphere adapters 25 

2.3.8 TCP/IP 25 

2.3.9 Service Component Architecture 26 

2.4 Transformation interfaces 27 

2.4.1 Compute node 27 

2.4.2 JavaCompute node 28 

2.4.3 PHPCompute node 28 

2.4.4 .NETCompute node 29 

2.5 Administering WebSphere Message Broker 29 


© Copyright IBM Corp. 2012. All rights reserved. 


v 



2.5.1 WebSphere Message Broker Explorer 30 

2.5.2 Broker sets 31 

2.5.3 Web Administration and record and replay 31 

2.6 Deploying applications 33 

2.7 Getting started 33 

2.7.1 Opening the Message Broker Toolkit 34 

2.7.2 Creating a new application 35 

2.7.3 Creating a new message flow 36 

2.7.4 Creating a broker 38 

2.7.5 Managing brokers 43 

2.7.6 Creating a BAR file for deployment 46 

2.7.7 Deploying the BAR file to a broker 48 

2.7.8 Executing WebSphere Message Broker commands 49 

2.8 Creating WebSphere MO queue managers and queues 50 

2.8.1 Creating queue managers 50 

2.8.2 Creating queues and queue managers using commands 50 

2.8.3 Creating queue managers and queues from the WebSphere MO Explorer 51 

Chapter 3. Using the tools for WebSphere Message Broker and .NET Integration . . 53 

3.1 Creating a .NETCompute node in a message flow 54 

3.1.1 Creating the messaging flow 54 

3.1 .2 Creating the code for the .NETCompute node 56 

3.1.3 Setting the properties for the .NETCompute node 59 

3.1.4 Deploying the application 60 

3.2 Hot swap deploys 62 

3.3 Using the Visual Studio debugger 63 

Chapter 4. Scenario: Bridging WebSphere MQ and Microsoft Message Queuing ... 67 

4.1 Scenario overview 68 

4.2 Receiving messages from MSMO 69 

4.2.1 Constructing a simple utility to read and write MSMQ messages 69 

4.2.2 Constructing and testing a basic message flow 78 

4.3 Mapping headers between MSMO and WebSphere MO 88 

4.4 Adding logging to your code 89 

4.5 Handling exceptions 93 

4.6 Sending messages to MSMQ 94 

4.6.1 Constructing the message flow 94 

4.6.2 Configuring the message flow 95 

4.6.3 Creating the .NET code 96 

4.6.4 Writing the code 96 

4.7 Distributed transactional coordination 103 

4.7.1 Manual transaction sample 103 

4.7.2 Testing the message flow 105 

4.8 Conversions 108 

Chapter 5. Scenario: Calling Microsoft Dynamics CRM from a message flow 109 

5.1 Scenario overview 110 

5.1 .1 SAP Request node for SAP Software 110 

5.1.2 Microsoft Dynamics CRM Online Ill 

5.1.3 Prerequisites for this scenario Ill 

5.2 Creating the message flow Ill 

5.2.1 Setting up the environment 114 

5.2.2 Creating and connecting the nodes 115 

5.2.3 Configuring the node properties 116 


vi Using WebSphere Message Broker V8 in Mid-Market Environments 



5.2.4 Broker configuration for SAP request nodes 127 

5.2.5 Writing the code for the SAP nodes 128 

5.2.6 Coding the ESQL for the Compute nodes 128 

5.2.7 Coding the Filter Request .NETCompute node 131 

5.2.8 Writing the code for the database operations 132 

5.2.9 Writing the code for accessing Microsoft Dynamics CRM Online 135 

5.2.10 Writing the code for the .NETCompute node (Create) - 

DB<->CreateCRMOnlineCustomer 142 

5.3 Deploying the message flow 144 

5.4 Testing the message flow 147 

5.4.1 Windows Forms Project: GUI Based 147 

5.4.2 Writing the code for the SubscribeToService form 151 

5.4.3 Running the test 157 

5.4.4 Using the test client from the Message Broker Toolkit 157 

5.5 Troubleshooting tips 161 

Chapter 6. Scenario: Integration Windows Communication Foundation in message 

flows - Part 1 163 

6.1 ClaimsProcessingWcfService overview 164 

6.2 Windows Communication Foundation 165 

6.2.1 WCFABCs 166 

6.2.2 WCF operation 168 

6.3 Developing the WCF Service 168 

6.3.1 Creating a Microsoft Visual Studio 2010 project for the WCF Service 168 

6.3.2 Setting the namespace for the project 169 

6.3.3 Modifying the classes created by the New Project Wizard 170 

6.3.4 Creating the required datatypes 172 

6.3.5 Creating private methods to serialize and deserialize the Datatypes 180 

6.3.6 Designing and implementing the service contract 184 

6.3.7 Building the WCF Service 229 

6.3.8 Configuring the WCF service 230 

6.3.9 Testing the WCF Service using the WCF Test Client 235 

6.4 Obtaining information about the service using MEX 246 

6.5 Generating WCF client code from a MEX enabled WCF service 248 

6.6 WCF hosting options 251 

6.6.1 Hosting using Visual Studio 251 

6.6.2 Hosting using a stand-alone application 251 

6.6.3 Hosting as a service 257 

6.6.4 Hosting in Internet Information Services (IIS) 265 

Chapter 7. Scenario: Integrating Windows Communication Foundation in message 

flows - Part 2 273 

7.1 Scenario overview 274 

7.1.1 Prerequisites 275 

7.2 Creating the message flow 276 

7.2.1 Preparing message models 276 

7.2.2 Creating the message flow 278 

7.2.3 Creating and connecting the nodes 280 

7.2.4 Configuring node properties 284 

7.2.5 Queue names 290 

7.3 Using the Mapping node to transform the input to the Canonical Message Format . . 290 

7.4 Transforming the SOAP input message 296 

7.5 Creating a .NETCompute node to consume the ClaimsProcessingWcfService 298 

7.5.1 Creating a constant to hold the namespace prefix 301 

Contents vii 



7.5.2 Adding the MEX-generated WCF client to the project 302 

7.5.3 Developing helper methods to interact with the WCF service 304 

7.5.4 Concurrency 304 

7.5.5 Flandling exceptions when invoking the WCF service 307 

7.5.6 Ensuring that the serviceClient is closed on flow deletion 309 

7.5.7 Creating methods to add datatypes to the message tree 309 

7.5.8 Creating a helper method to build Customer object from the Logical Message Tree 
311 

7.5.9 Preparing the ClaimsProcessingRequest object 312 

7.5.10 Adding the information from the WCF response into the message tree 314 

7.5.11 The CallWCFNode.EvaluateO method 316 

7.5.12 Handling failed tree navigations in the Evaluate() method 320 

7.5.13 Handling FaultExceptions in the Evaluate() method 321 

7.5.14 Verifying the completed CallWCFNode 322 

7.6 Routing the output 326 

7.6.1 Additional processing 326 

7.6.2 Routing the reply message 328 

7.7 Writing a .NETCompute node class to generate a payment message 330 

7.8 Processing incomplete results for the ViewOutstandingClaims operation 333 

7.9 Creating a Word document for email and print 337 

7.9.1 Preparing a letter template 338 

7.9.2 Creating a user-defined property for the template location 340 

7.9.3 Creating .NET code to generate a Word document using a template 341 

7.9.4 Using the EmailOutput node to send an email to the customer 347 

7.9.5 Using the FileOutput node to send the file for printing 348 

7.10 Using the Mapping node to transform the Canonical message to the output format 349 

7.1 1 Using a Compute node to transform the Canonical Message into a SOAP message 353 

7.12 Handling exceptions in the flow 353 

7.13 Building and deploying the Visual Studio project 358 

7.13.1 Building a solution 358 

7.14 Updating the properties for the .NETCompute nodes 359 

7.15 Building and deploying the Message Broker application 359 

7.15.1 Creating the BAR file 360 

7.15.2 Deploying the BAR file 360 

7.16 Testing the WebSphere Message Broker application 361 

7.16.1 Testing the MQ interface 362 

7.16.2 Testing the SOAP Interface 381 

7.17 Altering the scenario to use a SOAP over HTTP based binding 383 

7.17.1 Altering the WCF Service to expose an http based binding 383 

7.17.2 Altering a message flow to use an HTTP based binding 385 

Chapter 8. Integrating file transfer with WebSphere MQ FTE into the message flow 391 

8.1 Scenario overview 392 

8.2 Overview of the WebSphere MQ File Transfer edition 393 

8.2.1 Using WebSphere Message Broker as a bridge for FTE networks 394 

8.3 Preparing the broker environment for this scenario 395 

8.3.1 Creating the database 396 

8.3.2 Configuring the ODBC data source 401 

8.3.3 Preparing the file system structure 402 

8.4 Applications emulated in this scenario 403 

8.4.1 Branch application (FTE) 403 

8.4.2 Report Data Warehouse 409 

8.4.3 Volume Analysis System 414 

viii Using WebSphere Message Broker V8 in Mid-Market Environments 



8.5 Creating the main message flow 418 

8.5.1 Message flow overview 419 

8.5.2 Creating and connecting the nodes 420 

8.5.3 Creating a message definition 422 

8.5.4 Using FTE nodes 429 

8.5.5 Using aggregation in WebSphere Message Broker 431 

8.5.6 Producing multiple messages from the compute node 434 

8.5.7 Accessing databases from the database nodes 435 

8.5.8 Creating the queues for the FTESample application 438 

8.6 Running the scenario 438 

8.6.1 Troubleshooting tips 439 

8.6.2 Exploring the work of the scenario 440 

8.7 Extending the scenario 441 

Chapter 9. Integrating file transfer using Sterling Connect:Direct with your message 
flow 443 

9.1 Scenario overview 444 

9.2 Overview of the Sterling Connect:Direct 445 

9.3 Using WebSphere Message broker with Connect: Direct 446 

9.4 Preparing the Connect:Direct environment 447 

9.5 Preparing the logging database 453 

9.6 Configuring WebSphere Message Broker 456 

9.6.1 Creating a configurable service on WebSphere Message Broker 456 

9.6.2 Creating the message flow 458 

9.6.3 Creating the main message flow 459 

9.6.4 Creating the simulation flow 469 

9.6.5 Deploying the message flows and preparing the environment 472 

9.6.6 Sample file transfer data 473 

9.6.7 Testing the message flow 473 

Appendix A. Additional material 485 

Locating the Web material 485 

Using the Web material 485 

Downloading and extracting the Web material 486 

Related publications 487 

IBM Redbooks 487 

Online resources 487 

Help from IBM 488 


Contents ix 



Using WebSphere Message Broker V8 in Mid-Market Environments 



Notices 


This information was developed for products and services offered in the U.S.A. 

IBM may not offer the products, services, or features discussed in this document in other countries. Consult 
your local IBM representative for information on the products and services currently available in your area. Any 
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, 
program, or service may be used. Any functionally equivalent product, program, or service that does not 
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to 
evaluate and verify the operation of any non-IBM product, program, or service. 

IBM may have patents or pending patent applications covering subject matter described in this document. The 
furnishing of this document does not give you any license to these patents. You can send license inquiries, in 
writing, to: 

IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A. 

The following paragraph does not apply to the United Kingdom or any other country where such 
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION 
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR 
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, 
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of 
express or implied warranties in certain transactions, therefore, this statement may not apply to you. 

This information could include technical inaccuracies or typographical errors. Changes are periodically made 
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make 
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time 
without notice. 

Any references in this information to non-IBM websites are provided for convenience only and do not in any 
manner serve as an endorsement of those websites. The materials at those websites are not part of the 
materials for this IBM product and use of those websites is at your own risk. 

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring 
any obligation to you. 

Information concerning non-IBM products was obtained from the suppliers of those products, their published 
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the 
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the 
capabilities of non-IBM products should be addressed to the suppliers of those products. 

This information contains examples of data and reports used in daily business operations. To illustrate them 
as completely as possible, the examples include the names of individuals, companies, brands, and products. 
All of these names are fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 

COPYRIGHT LICENSE: 

This information contains sample application programs in source language, which illustrate programming 
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in 
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application 
programs conforming to the application programming interface for the operating platform for which the sample 
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, 
cannot guarantee or imply reliability, serviceability, or function of these programs. 


© Copyright IBM Corp. 2012. All rights reserved. 


xi 



Trademarks 


IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines 
Corporation in the United States, other countries, or both. These and other IBM trademarked terms are 
marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US 
registered or common law trademarks owned by IBM at the time this information was published. Such 
trademarks may also be registered or common law trademarks in other countries. A current list of IBM 
trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml 

The following terms are trademarks of the International Business Machines Corporation in the United States, 
other countries, or both: 

AIX® IBM® 

CICS® IMS™ 

DataPower® Informix® 

DB2® MVS™ 

developerWorks® Redbooks® 

The following terms are trademarks of other companies: 

Connect:Direct, Sterling Commerce, and N logo are trademarks or registered trademarks of IBM International 
Group B.V., an IBM Company. 

Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, 
other countries, or both. 

Java, and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its 
affiliates. 

UNIX is a registered trademark of The Open Group in the United States and other countries. 

Linux is a trademark of Linus Torvalds in the United States, other countries, or both. 

Other company, product, or service names may be trademarks or service marks of others. 


Redbooks (logo) <^® 
solidDB® 

Tivoli® 

WebSphere® 

z/OS® 


xii 


Using WebSphere Message Broker V8 in Mid-Market Environments 


Preface 


IBM WebSphere® Message Broker is a lightweight, advanced enterprise service bus (ESB) 
that provides a broad range of integration capabilities that enable companies to rapidly 
integrate internal applications and connect to partner applications. Messages from business 
applications can be transformed, augmented and routed to other business applications. The 
types and complexity of the integration required will vary by company, application types, and a 
number of other factors. 

Processing logic in WebSphere Message Broker is implemented using message flows. 
Through message flows, messages from business applications can be transformed, 
augmented, and routed to other business applications. Message flows are created by 
connecting nodes together. A wide selection of built-in nodes are provided with WebSphere 
Message Broker. These nodes perform tasks that are associated with message routing, 
transformation, and enrichment. Message flows are created and tested using the Message 
Broker Toolkit, a sophisticated, easy-to-use programming tool that provides a full range of 
programming aids. 

This IBM® Redbooks® publication focuses on two specific integration requirements that 
apply to many midmarket companies. The first is the ability to use WebSphere Message 
Broker to integrate Microsoft.NET applications into a broader connectivity solution. 
WebSphere Message Broker V8 introduces the ability to integrate with existing Microsoft 
.NET Framework applications. A .NET assembly can be called from within a message flow 
and the WebSphere Message Broker runtime can host and run .NET code. Solutions 
explored in this book cover connectivity to applications using Windows Communications 
Framework (WCF), Microsoft Message Queuing, Microsoft Dynamics CRM, and other 
Microsoft applications. 

The second is the ability to integrate WebSphere Message Broker with file transfer networks, 
specifically with WebSphere MQ File Transfer Edition and IBM Sterling Connect Direct. 


The team who wrote this book 

This book was produced by a team of specialists from around the world working at the 
International Technical Support Organization, Raleigh Center. 

Vinicius D. G. Braganca has worked at IBM for eleven years in various Information 
Technology (IT) areas. Before joining the IBM Software Group, he worked for IBM Global 
Services as an Integration Architect. He has over 14 years of experience working on IBM 
Integration Technologies and has been involved with the planning, design, implementation, 
management, and problem analysis of IBM solutions. Now he is an l/T Architect Advisor for 
the IBM Worldwide WebSphere Business Partners Organization at the Latin America team in 
Sao Paulo, Brazil. 

Minsung Byun is a Software Engineer at Research Triangle Park, North Carolina. He has 
been at IBM for nine years and the last six years of which were as a member of the 
WebSphere Message Broker Level 2 support team. He has a Bachelor’s degree in Chemical 
Engineering from Inha University and a Masters of Science in Computer Science from Akron 
University. 
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Broker. He provides final line support to WebSphere Message Broker customers including 
establishing best practices, problem analysis and resolution, defect support, and delivery of 
new function for in service releases. 

Kiran Darbha is an Advisory Software Engineer working for IBM India Software Labs. He has 
nine years of experience in the IT industry with expertise in the Windows platform, Global 
Transactions, and WebSphere Service Oriented Middleware. Kiran is the Technical Leader for 
the WebSphere MQ .NET Stack and is currently involved with design and development of the 
.NET component for MQ to enable .NET developers access to WebSphere messaging. Apart 
from his primary responsibilities, he is actively involved in Innovation, New Technology 
developments, and Product consumability. Kiran has wide expertise and works extensively on 
various Microsoft .NET Technologies. 

Jefferson Lowrey has more than 20 years of IT experience, ranging from desktop support 
through server administration and network configuration to architecting, developing, and 
maintaining enterprise applications and business-critical file transfer systems. Jeff has deep 
experience with a broad range of products in the WebSphere family, with a concentration on 
messaging and connectivity. Jeff has worked for financial services companies, mid-sized 
retailers, insurance companies, medical and pharmaceutical companies, and government 
agencies. 

Jeff started programming computers at age 10, and got his first professional programming job 
at age 1 9 working on a team that wrote data analysis and collection software for cryogenic 
equipment at NASA Goddard Space Flight center. He went on to job roles in help desk and 
various other support and programming roles on the Macintosh platform until he started 
writing Windows software to encrypt, decrypt, and transfer files over FTP and SMTP for a 
student loan company. This lead to him learning WebSphere MQ and Message Broker as a 
means of routing and identifying data to be sent to the correct external and internal parties. 
Within five years, Jeff was an internationally recognized expert on these products, and was 
hired by IBM as a consultant with a focus on Message Broker. 

Jeff has experience working with a wide range of WebSphere products, including App Server, 
Portal Server and with IBM DataPower® to a lesser extent. Jeff brings deep skills in software 
architecture, design, implementation, administration, and management to all of his projects. 

Pavel Malyutin is an IBM Certified Level 2 (Master) IT Specialist at IBM Russia, Moscow. He 
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WebSphere Message Broker for 
mid-market solutions 


WebSphere Message Broker is a lightweight, advanced enterprise service bus (ESB) that 
enables the integration of data sources from a wide range of platforms across both 
service-oriented architecture environments (SOA) and non-SOA environments. 

With WebSphere Message Broker, organizations of any size can eliminate point-to-point 
connections and batch processing. Moving forward in this way increases business flexibility 
and smart interoperability of systems regardless of platform, protocol, or data format. 

WebSphere Message Broker is frequently associated with large enterprise solutions because 
of the capabilities for connecting to enterprise information systems, such as SAP, Siebel, 

IBM CICS®, and others. However, IBM also recognized a growing need for ESB capabilities 
in midmarket companies. 

With this in mind, new features and editions of WebSphere Message Broker provide targeted 
capability for this growing segment. 
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1.1 WebSphere Message Broker 


You can use IBM WebSphere Message Broker to connect applications together, regardless of 
the message formats or protocols that they support. 

This connectivity means that your diverse applications can interact and exchange data with 
other applications in a flexible, dynamic, and extensible infrastructure. WebSphere Message 
Broker routes, transforms, and enriches messages from one location to any other location: 

► The product supports a wide range of protocols: WebSphere MQ, JMS 1 .1 , HTTP and 
HTTPS, Web Services (SOAP and REST), File, Enterprise Information Systems (including 
SAP and Siebel), and TCP/IP. 

► It supports a broad range of data formats: Binary formats (C and COBOL), XML, and 
industry standards (including SWIFT, EDI, and HIPAA). You can also define your own data 
formats. 

► It supports many operations, including routing, transforming, filtering, enriching, 
monitoring, distribution, collection, correlation, and detection. 

Message Broker works with various hardware and software to match, route, convert, 
transform, identify, and distribute data. Figure 1-1 provides an overview of these functions. 




MATCHES and ROUTERS communications 
between services 


( 's 

^Vf ] CONVERTS 

J between different transport protocols 



TRANSFORMS 

between different data formats 
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Figure 1-1 Message Broker overview 


1.1.1 Message processing 

Processing logic in WebSphere Message Broker is implemented using message flows. 
Through message flows, messages from business applications can be transformed, 
augmented, and routed to other business applications. Message flows are created by 
connecting nodes together. A wide selection of built-in nodes are provided with WebSphere 
Message Broker. These nodes perform tasks that are associated with message routing, 
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transformation, and enrichment. Message flows are created and tested using the WebSphere 
Message Broker Toolkit, which is a sophisticated, easy-to-use programming tool that provides 
a full range of programming aids. 

The base capabilities of WebSphere Message Broker are enhanced by SupportPacs that 
provide a wide range of additional enhancements. 

Message routing 

WebSphere Message Broker provides a variety of nodes through which connectivity is 
provided for both standards and non-standards-based applications and services. Routing can 
be point-to-point or based on matching the content of the message with a pattern that is 
specified in a node. 

Aggregation is an advanced form of message routing. With aggregation, a request message 
is received, and multiple new request messages are generated. Each new message is routed 
to its destination using a request-reply interaction. WebSphere Message Broker tracks the 
process, collecting each response, and recomposing them into a single output message. 

Collection is another advanced form of message routing. With collection, a set of related 
individual messages is assembled through a time-independent process and a single 
message or response structure is created. WebSphere Message Broker handles all of the 
details of storing incoming messages and correlating them together to produce a completed 
structure based on the requirements. Further transformation logic can then be applied to the 
results to produce the necessary output. 

Transport protocol conversion 

WebSphere Message Broker enables simplified connectivity between applications or 
business processes that use disparate transport protocols, including Web Services (SOAP 
and REST), HTTP(S), Java Message Service (JMS) 1.1, WebSphere MQ, file transfer 
protocols, CICS, IBM IMS™, TCP/IP, Service Component Architecture (SCA), enterprise 
information systems (SAP, Siebel, JD Edwards, PeopleSoft), and user-defined transports. 

Message transformation and enrichment 

One of the key capabilities of WebSphere Message Broker is the transformation and 
enrichment of in-flight messages. This capability enables business integration without the need 
for any additional logic in the applications, for example, an application that generates 
messages in a custom format can be integrated with an application that only recognizes XML. 
Enriched in-flight messages also provides a powerful mechanism to unify organizations 
because business information can now be distributed to applications that handle completely 
separate message formats. 

In WebSphere Message Broker, message transformation and enrichment are dependent 
upon a broker understanding the structure and content of the incoming message. 
Self-defining messages, such as XML messages, contain information about their own 
structure and format. However, before other messages, such as custom format messages, 
can be transformed or enhanced, a message definition of their structure must exist. The 
Message Broker Toolkit contains facilities for defining messages to the WebSphere Message 
Broker. Message Broker can import and reuse message definitions that are developed using 
XML schemas and message definitions from previous versions of the product. Message 
Broker version 8 introduces a new parser and message definition model using the Data 
Format Description Language (DFDL). DFDL can create models that represent complex text 
and binary message formats including COBOL records, CSV structures, industry standard 
(SWIFT, HIPAA) messages, and more. DFDL can be used to model any message that is not 
defined using an XML schema. The DFDL parser and modeler are faster and more advanced 
than the previous TDS and CWF functions in WebSphere Message Broker version 7. 
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Using parsers and message sets, WebSphere Message Broker can validate and check that 
incoming messages comply with the format that is defined in the message set. A flow can be 
constructed to reject and handle non-compliant messages. Additionally, complex 
manipulation of message data can be performed using extended SQL (ESQL), Java, and 
PHP facilities. These facilities are provided in the Message Broker Toolkit or using a .Net 
program developed using Microsoft Visual Studio 2010. 

WebSphere Transformation Extender can be integrated into the WebSphere Message Broker 
ESB solution to further extend the existing capabilities. 


1.1.2 Connectivity options 

WebSphere Message Broker provides support for a variety of messaging transport protocols 
through a series of built-in nodes. These nodes enable robust and scalable applications to be 
developed without having to write code to support individual transport functions. The available 
nodes for connectivity include: 

► WebSphere MQ 

The WebSphere MQ Enterprise Transport supports WebSphere MQ applications that 
connect to WebSphere Message Broker to benefit from message routing and 
transformation options. 

► Java Message Service (JMS) 1 .1 

The WebSphere Message Broker JMS Transport sends and receives JMS messages 
using destinations that are accessible through a JMS provider. The built-in JMS nodes act 
as JMS clients. The JMS nodes work with WebSphere MQ JMS provider, WebSphere 
Application Server, and any other JMS provider that conforms to the Java Message 
Service Specification VI .1 . 

► WebSphere MQ/JMS 

WebSphere Message Broker provides support that includes the ability to transform MQ 
messages to JMS and vice versa. 

► SOAP-based Web services 

The WebSphere Message Broker Web services support includes both provider and 
consumer scenarios, WS-Security and WS-Addressing support, WS-RM (Web Services 
Reliable Messaging), and integration with DataPower appliances for Web service security. 
Integrated support for WebSphere Service Registry and Repository is also provided. 
Message flows can access, use, and select specific service registry entities dynamically at 
runtime. 

► HTTP and HTTPS 

The WebSphere Message Broker HTTP Transport connects applications that use the 
HTTP protocol. Message flows can use the HTTP transport to work with SOAP-based 
Web services, other Web services standards, such as REST or XML-RPC, and general 
HTTP messaging, where the payload might or might not be XML. 

► File 

File processing support is provided for: 

- File processing of local (to the broker) files or remote files using FTP and SFTP 

- Managed file transfer using WebSphere MQ File Transfer Edition 

- Managed file transfer using IBM Sterling Connect: Direct® 


4 Using WebSphere Message Broker V8 in Mid-Market Environments 



Java Connector Architecture (JCA) Adapters 

The WebSphere Adapters nodes can be used to communicate with enterprise information 
systems (EIS). WebSphere Message Broker provides message flow nodes that support 
connectivity with an SAP server, TwineBall, Siebel Business Applications server, 
PeopleSoft Enterprise, and JD Edwards EnterpriseOne applications. 

TCP/IP 

WebSphere Message Broker provides support for TCP/IP connectivity of existing 
applications that use raw TCP/IP sockets for transferring data. 

Service Component Architecture 

SCA nodes allow interoperability with WebSphere Process Server. The SCA nodes 
support inbound and outbound scenarios with WebSphere Process Server and 
WebSphere Enterprise Service Bus. 

CICS Transaction Server for IBM z/OS® 

Message flows can create a client connection with CICS Transaction Server for z/OS 
either directly or through CICS Transaction Gateway for Multiplatforms. Message flows can 
call programs that are running in the target CICS region. CICS can also be accessed 
through web services or over WebSphere MQ. 

IBM Information Management System (IMS) 

Message flows can create a client connection with IMS using IMS Connect, WebSphere 
MQ-IMS bridge, and the IMS SOAP Gateway. 

Email 

Message flows can send or receive emails. Email can be delivered to an email server that 
supports SMTP. Email can be received from an email server that supports Post Office 
Protocol 3 (POP3) or Internet Message Access Protocol (IMAP). 

CORBA 

Use CORBA nodes in message flows to connect to CORBA Internet Inter-Orb Protocol 
(MOP) applications. 

Databases 

Message flows can access user databases on IBM DB2®, IBM Informix®, Microsoft SQL 
Server, Oracle, IBM solidDB®, and Sybase. Transactional (XA) and non-transactional 
connections are supported. Both ODBC and JDBC type 4 connections are supported. 

Routing nodes 

Use the Route node to direct messages that meet certain criteria down different paths of a 
message flow. Route nodes can be directed to filter, publish, subscribe, label, aggregate, 
collect, sequence, and re-sequence. 

Transformation nodes 

Use the transformation nodes to transform a message from one type to another and 
support integration. Transformation nodes include Microsoft .Net, mapping, XSL 
Transform, Compute, JavaCompute, and PHPCompute. 

Construction nodes 

Use construction nodes to manage and create subflows. These subflows can control the 
order of messages, force message flow during error processing or exceptions, parsing, 
and versions of subflow. Construction nodes include input, output, trace, throw, trycatch, 
floworder, pass-through, and reset content descriptor. 
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Validation nodes 


Use the validation node to check that the message that arrives is as expected (message 
domain, message set, and message type) and to check that the content of the message is 
correct by selecting message validation. The check node is deprecated in Version 6 and 
higher and can be replaced with validation nodes. 

► Security nodes 

Use the SecurityPEP node to invoke the message flow security manager at any point in 
the message flow. These can be placed between input, output, and request nodes. 

► Timer nodes 

The TimeoutControl node processes an input message with a timeout request. It validates 
the timeout request message, stores the message, and propagates the message 
(unchanged) to the next node in the message flow. The TimeoutNotification node can be 
paired with a TimeoutControl node for events that must happen at a specific time, or 
stand-alone based on the timing function desired. 


1.1.3 WebSphere Message Broker editions 

WebSphere Message Broker is now available in a number of different editions. Each edition is 
designed to provide targeted capability to address the key integration requirements of 
companies within a particular market segment. 

WebSphere Message Broker also supports a seamless upgrade from one edition of the 
product to the next without the need to reinstall. The ability to seamlessly upgrade provides 
businesses with the flexibility to change their original choice of edition as their integration 
needs grow. The following list outlines the various WebSphere Message Broker Editions: 

► WebSphere Message Broker Trial Edition 

The 90-day Trial Edition can be downloaded from the web at no charge. This edition 
enables you to evaluate all of the capabilities of WebSphere Message Broker to decide 
which edition is most appropriate for your needs. 

► WebSphere Message Broker Express Edition 

The Express Edition provides simple, robust connectivity for small businesses or single 
departments. This connectivity includes the ability to integrate common applications and 
data sources. It also includes the ability to perform basic data transformation and 
mapping. 

A list of the message flow nodes that are available in this edition are in the following 
WebSphere Message Broker Information Center topic: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/topic/com.ibm.etools.mf 

t.doc/an67720_.htm. 

► WebSphere Message Broker Standard Edition 

The Standard Edition augments Express to provide additional integration capabilities 
required by medium-sized businesses. These integration capabilities include the ability to 
perform more complex operations on data, for example, to aggregate data from multiple 
sources or sequence messages to ensure that data arrives in a consistent manner. It also 
includes connectivity to mainframe systems, such as CICS or IMS, and to CRM, ERP, EIS 
systems. 
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► WebSphere Message Broker 

WebSphere Message Broker augments Standard to provide the performance, scalability, 
and management required by large enterprises. This includes the ability to handle large 
volumes of business-critical traffic and provide separation of individual department's data 
for security, maintenance, or other operational management purposes. 

► WebSphere Message Broker Remote Adapter Deployment 

The Remote Adapter Deployment Edition provides a specific solution for businesses that 
require basic connectivity to a broad range of endpoints, including applications, such as 
ERP or EIS systems. 

A list of the message flow nodes that are available in this edition are in the following 
WebSphere Message Broker Information Center topic: 

http : / / publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/topi c/com. i bm.etool s.mf 
t.doc/an67720_.htm. 


1.2 WebSphere Message Broker for midmarket 

WebSphere Message Broker provides a broad range of integration capabilities that enable 
companies to rapidly integrate internal applications and connect to partner applications. The 
types and complexity of the integration required vary by company, application types, and a 
number of other factors. 

This book focuses on two specific integration requirements that apply to many midmarket 
companies: 

► The first is the ability to use WebSphere Message Broker to integrate Microsoft .NET 
applications into a broader connectivity solution. 

► The second is the ability to use WebSphere Message Broker in conjunction with 
WebSphere MQ File Transfer Edition to transfer and use business data held in files. 


1.2.1 Microsoft .Net integration 

WebSphere Message Broker V8 introduces the ability to integrate with existing Microsoft 
.NET Framework applications. A .NET assembly can be called from within a message flow 
and the WebSphere Message Broker runtime can host and run .NET code. 

A new node called the .NETCompute node was added to allow the message data to be 
processed using a Common Language Runtime (CLR)-compliant .NET programming 
language. Some CLR compliant languages options are C#, Visual Basic (VB), F#, or 
C++/Common Language Infrastructure (CLI). This new node can be used to build messages, 
interact with .NET or COM applications, transform messages from one format to another, 
copy messages, route messages, and modify messages. The node must be configured with a 
.NET assembly file that contains the code that performs the logic of the node. The Message 
Broker Toolkit provides integration with Microsoft Visual Studio 2010, allowing you to develop 
.NET solutions in Visual Studio and integrate them into the message flow. 

The WebSphere Message Broker runtime hosts and runs .NET code that is associated with a 
WebSphere Message Broker solution. The .NET code is not executed in a stand-alone 
process. Message flows containing .NET code can only be deployed and run successfully on 
brokers that are on Windows platforms. 
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WebSphere Message Broker can also integrate with Microsoft .NET applications that expose 
a Windows Communication Framework web service interface. This is less efficient than direct 
invocation through the .NETCompute node, but enables non-Windows brokers to remotely 
invoke .NET business logic. 

WebSphere Message Broker can act as a bridge between IBM messaging technology 
(WebSphere MQ) and Microsoft messaging technology (MSMQ). This bridge enables the 
creation of solutions that span the two messaging environments. 


1.2.2 File processing and transfer 

Many business applications and user-based processes consume and save data as files. It is a 
common practice for companies of all sizes to create lots of small applications and processes 
to ensure that files created by one application are moved to the correct places to be 
consumed by other applications and users. This leads to a complicated IT infrastructure and 
multiple, different solutions for management and operational awareness of issues with these 
transfers. 

WebSphere Message Broker provides the capability to integrate file-based business 
applications, replacing manual, script-based or batch file processing. Files can be read and 
written locally or remotely using FTP or SFTP. WebSphere MQ File Transfer Edition augments 
this by providing secure, reliable delivery of files to and from WebSphere Message Broker in 
place of FTP or SFTP. 


1.3 Additional resources 

► IBM for Midsize Business on Facebook 

http://www.facebook.com/Mi dmarketIBM?v=app_228046053890511#!/Mi dmarketIBM?sk=wa 
11 

► Using Microsoft .NET in WebSphere Message Broker V8 - DeveloperWorks tutorials 

http : //www. i bm.com/devel operworks/vi ews/websphere/1 i braryvi ew. j sp?search_by=Usi 
ng+Mi crosoft+.NET+i n+WebSphere+Message+Broker+V8 
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Introduction to WebSphere 
Message Broker V8 


In this chapter, we introduce the features of WebSphere Message Broker. We also introduce 
the runtime architecture and the message flows that perform the enterprise service bus 
functionality. 

Specifically, we cover the following topics: 

► Runtime architecture of WebSphere Message Broker 

► Development environment of WebSphere Message Broker 

► Connectivity options 

► Transformation interfaces 

► Administering WebSphere Message Broker 

► Deploying applications 

► Getting started 

► Creating WebSphere MQ queue managers and queues 


© Copyright IBM Corp. 2012. All rights reserved. 
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2.1 Runtime architecture of WebSphere Message Broker 


WebSphere Message Broker consists of a development environment where message flows 
and message sets are designed and developed and a runtime environment where the 
message flows executes. Figure 2-1 shows an overview of the WebSphere Message Broker 
architecture. 



Figure 2- 1 Architecture of WebSphere Message Broker 


2.1.1 Broker 

The broker is a set of application processes that host and run message flows. When a 
message arrives at the broker from a business application, the broker processes the 
message before passing it to one or more other business applications. The broker routes, 
transforms, and manipulates messages according to the logic that is defined in their message 
flow applications. Each broker uses an internal repository in the local file system to store the 
message flows, configuration data, and the message sets that are deployed to it. 


2.1.2 Execution groups 

Execution groups are processes that host message flows. The execution groups facilitate the 
grouping of message flows within the broker with respect to functionality, load balancing, or 
other necessary qualifications. Each broker contains a main execution group. Additional 
execution groups can be created if they are given unique names within the broker. 

Each execution group is a separate operating system process. Therefore, the contents of an 
execution group remain separate from the contents of other execution groups within the same 
broker. This separation can be useful for isolating pieces of information for security because 
the message flows execute in separate address spaces or as unique processes. Execution 
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groups can also be used to scale the broker, for example, in multi-processer platforms, 
different execution groups can be assigned to various processors. 

Message flow applications are deployed to a specific execution group. To enhance 
performance, additional message flow instances can be deployed to an execution group. 
Each additional instance allocates an additional thread to host the message flow application. 
The number of threads can be increased using a per message flow basis, based on the 
processing requirements of that message flow. For each additional instance, an additional 
thread is started in the execution group to process the incoming messages at run time. 


Additional information: For more information about designing for performance in 
WebSphere Message Broker, refer to the SupportPacs IP04 at: 

http : //www-01 . i bm.com/ support/docvi ew.wss?rs=171&ui d=swg24006518&l oc=en_US&cs=u 
t f -8&1 ang=en 


2.2 Development environment of WebSphere Message Broker 

In this section, we provide an introduction to the development environment of WebSphere 
Message Broker and the various mediation capabilities that it offers. 

2.2.1 WebSphere Message Broker Toolkit 

The WebSphere Message Broker Toolkit is an integrated development environment (IDE) and 
graphical user interface (GUI) based on the Eclipse platform. Application developers can use 
the Message Broker Toolkit to create message flows and the associated artifacts and to 
deploy them to the execution groups. 

Broker Application Development perspective 

The Broker Application Development perspective is the default perspective that is displayed 
the first time that you start the Message Broker Toolkit. Application developers work in this 
perspective to develop and modify message sets and message flows. Figure 2-2 on page 12 
shows the Broker Application Development perspective with a message flow open in the 
Message Flow editor. 
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Figure 2-2 Application development perspective 


Figure 2-2 shows that the JMS folder within the Palette is open in the Message Flow Editor. 

The flow, shown in Figure 2-2, also starts with a JMSInput node. The middle terminal of this 
node, which is the out terminal, is wired to the input terminal on a subflow. The out terminal of 
that subflow was again wired to the in terminal of another subflow. These wires indicate the 
logical steps that the message flow performs. Each node or subflow is invoked by a 
connection coming in to one of its input terminals and forwards a response to an output 
terminal, based from the logic performed inside the node itself. 


2.2.2 Applications and libraries 

Message Broker Version 8 introduces a new concept of packaging broker solutions. Every 
deployable artifact now belongs to an application or a library. Resources can be developed 
outside of an application or library but when deployed they are still part of a default 
application. Applications and libraries provide runtime isolation of source code and message 
models for an increased level of change control and fault isolation. 
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2.2.3 Message flows 


Message flows are created by adding nodes to the workspace, defining properties for these 
nodes, and wiring the nodes together in a logical flow. Nodes are dragged onto the message 
flow document from the palette located on the right. Individual nodes have terminals that 
represent connection points to these nodes. Flow logic is built by adding lines between the 
terminals of each of the nodes in the flow to direct the order of processing. Each node then 
performs a specific function or type of function within the flow. Table 2-1 lists the nodes that 
the Message Broker Toolkit provides for message flow development. 

You can find details about these nodes in the WebSphere Message Broker Information 
Center at: 

http : //publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/i ndex. jsp 

You can add nodes by using SupportPacs. For a list of SupportPacs, see the Business 
Integration, WebSphere MQ SupportPacs page at: 

http://www-l.ibm.com/support/docvi ew.wss?rs=849&ui d=swg27007205 


Table 2-1 Available node types in a WebSphere Message Broker 


Category 

Input/output type node 

Flow development nodes 

WebSphere MQ 

MQInput 

MQOutput 

MQReply 

MQGet 

MQHeader 

MQOptimizedFlow (deprecated) 

JMS 

JMSInput 

JMSOutput 

JMSReply 

JMSReceive 

JMSHeader 

MQJMSTransform 

JMSMQTransform 

HTTP 

HTTPInput 

HTTPRequest 

HTTPReply 

HTTPHeader 

Routing 


Filter 

Label 

Publication 

RouteToLabel 

Route 

AggregateControl 

AggregateRequest 

AggregateReply 

Collector 

Resequence 

Sequence 

Transformation 


.NetCompute 

Mapping 

XSLTransform 

Compute 

JavaCompute 

PHPCompute 
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Category 

Input/output type node 

Flow development nodes 

Construction 


Input 

Output 

Throw 

Trace 

TryCatch 

FlowOrder 

Passthrough 

ResetContentDescriptor node 

Database 

Databaselnput 

Database 
Database Retrieve 
Database Route 

Validation 


Check (Deprecated) 
Validate 

Timer 


TimeoutControl 

TimeoutNotification 

Corba 


CorbaRequest 

SCA 

SCAInput 

SCAReply 

SCARequest 

SCAAsyncRequest 

SCAAsyncResponse 

Web Services 

SOAPInput 

SOAPReply 
SOAPRequest 
SOAPAsyncRequest 
SOAPAsyncResponse 
SOAPEnvelope 
SOAPExtract 
Registry Lookup 
Endpoint Lookup 

WebSphere 

Adapters 

PeopleSoftlnput 

SAPInput 

Siebellnput 

JDEdwardsInput 

TwineBalllnput 

PeopleSoftRequest 

SAPRequest 

SAPReply 

SiebelRequest 

JDEdwardsRequest 

TwineBallRequest 

File 

Filelnput 

FileOutput 

FTEInput 

FTEOutput 

CDInput 

CDOutput 

FileRead 

Email 

Emaillnput 

EmailOutput 


TCP/IP 

TCPIPCIientlnput 

TCPIPCIientOutput 

TCPIPServerlnput 

TCPIPServerOutput 

TCPIPCIientReceive 

TCPIPServerReceive 

CICS 


CICSRequest 

IMS 


IMSRequest 
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Category 

Input/output type node 

Flow development nodes 

Security 


SecurityPEP 


2.2.4 Message 

A message is a collection of data that one application sends to another. This data can be 
business data or elements that are arranged in a predefined structure or a sequence of bytes. 

When a message arrives at a message flow input node in a broker, the parser that is 
configured at the input node interprets and creates a logical tree representation. This tree 
representation is created from the bitstream of the message data, which is known as the 
message assembly. The tree format can then be easily manipulated and updated within the 
message flow using ESQL, Java, PHP or .NET. After the message is processed, the parser 
converts it back into a bitstream at the output. The message assembly consists of four tree 
structures: 

► Message tree structure: The message tree includes all of the headers in the message, 
properties subtree, and the message body. 

► Environment tree structure: The environment tree stores information in the form of 
variables as the message passes through the message flow. It is typically used to store 
information regarding accounting and statistics or correlation attributes that are associated 
with broker monitoring events. The environment tree is always included in the message 
and its contents are retained in the output message. 

► Local environment tree structure: This tree also stores information in the form of variables; 
however, these variables can be referenced or updated in the message flow. Local 
environment tree structure is composed of several subtrees, such as variables, 
destination, file, SOAP, service-registry, wildcard, adapter, TCP/IP, or a written destination. 

► Exception list tree structure: This tree contains information about exceptions that can 
occur during message processing. The exception list tree is typically built when an 
exception is thrown and the message processing is suspended. 


Additional information: For more information about the Logical tree structure, refer to the 
following topic in the Information Center: 

http : //publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/i ndex. j sp? topi c=%2Fcom. 
i bm. etool s .mft . doc%2Fac00490 . htm 


2.2.5 Message modeling 

Message modeling is a way to predefine the message formats that are used by applications in 
the broker infrastructure. Modeling is usually used for message formats that are not 
self-defining because the parser must have access to the predefined model that describes 
the message. Modeling might also be used for runtime validation of incoming messages and 
enhanced parsing of XML messages. Message models construct the logical message tree 
from raw data and serialize a logical message tree into a bitstream. 

WebSphere Message Broker V8 includes a new modeler and parser built around the open 
standard Data Format Description Language (DFDL). Previous models built using Message 
Sets can be reused in WebSphere Message Broker V8 but cannot be created. 
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Message models in version 8 are stored in XML schema files. DFDL describes the contents 
of non-XML formatted data using XML schemas, so all message models can be stored and 
deployed in a common format. 

WebSphere Message Broker V8 includes sophisticated tooling around DFDL, including the 
ability to test a DFDL model directly in the Message Broker Toolkit. This function allows you to 
test parsing a message and serializing a message tree. This can significantly shorten the time 
it takes to develop and prove out a message model. 

Message modeling concepts 

All messages arrive in the broker as binary data. To understand them, the broker uses 
parsers that split the message into logical parts and create a logical message model instance. 
The logical message model instance in the broker is always represented as a tree, with one 
root element that corresponds to the name of the parser used. 

There are two different kind of parsers in WebSphere Message Broker: 

► Programmatic: These parsers understand the message model because the message 
model is built into them. Each message format needs a specific parser. Examples of these 
parsers are: 

- MIME: Parses internet MIME messages form. 

- BLOB: Treats messages as binary data. This is the default parser. 

- XMLNSC: Creates a logical structure from an XML message. If you do not specify a 
message set, all elements and attributes are treated as string, so additional casting is 
required during processing. 

► Descriptive: With this type of parser, the message format is encoded in a model. A general 
purpose parser program uses the model when parsing. The model can be used as-is or 
generated into code. Examples model-driven parsers include: 

- DFDL: Data Format Description Language is an open-standard XML-based language 
used to define the structure of formatted data in a way that is independent from the 
data format itself. The DFDL domain can be used to parse and write a wide variety of 
message formats, and is primarily intended for non-XML message formats. 
WebSphere Message Broker provides tooling for modeling and testing DFDL data at 
design time. You can create a logical model of the message or import it from a file, test 
how it will be serialized into binary format, and test how binary data will be parsed into 
the logical model. Because all of these steps are executed at design time and do not 
require the broker, DFDL development is easier and faster than using MRM. DFDL is 
not intended to be used to model XML documents. Use normal XML Schema files to 
model XML. 

- MRM: Message Repository Manager (MRM) is the predecessor of DFDL and uses 
similar techniques for describing the structure of formatted data using a type of XSD 
schema, except that it can also model XML data. The MRM format of data definition 
was only used in WebSphere Message Broker. 

- XMLNSC with XML schema: The XMLNSC parser can execute a validation of the 
message against the message model and, optionally, can cast all data from string 
representation to actual data type from an XML schema. The XMLNSC parser can be 
used both as a programmatic parser (a generic XML parser) and as a descriptive 
parser. This is used when you create the XML schema for the message, deploy it to the 
broker, and select message validation in the message flow. 
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2.2.6 Pattern instances 


Patterns are reusable solutions that encapsulate a tested approach in solving common 
architectural, deployment, and design tasks in a particular context. Patterns can be used to 
generate customized solutions to a recurring problem in a more effective way. Patterns in 
WebSphere Message Broker can be referenced to provide guidance in implementing 
solutions. Pattern specifications typically include the description of identified solutions. 
Patterns greatly reduce the development cycles because the resources can be generated 
from a set of predefined templates, thus increasing the efficiency. Patterns improve quality 
through asset reuse and the implementation of error handling and logging functions. 

The Message Broker Toolkit displays pattern instances in the Patterns Explorer view, which 
provides a list of patterns and details about each of the patterns. The description in the help 
can guide you towards a suitable pattern to solve a particular problem. Figure 2-3 shows the 
list of available patterns that are provided in the Pattern Explorer. 
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Figure 2-3 Patterns Explorer 


Patterns: For more information about using patterns and pattern categories, search 
patterns in the WebSphere Message Broker Information Center at: 

http : //publ ib.boulder.ibm.com/infocenter/wmbhel p/v8r0m0/i ndex. jsp?topic=/com.ib 
m.etool s.mft.doc/ac67850_.htm 

You can get additional information about WebSphere Message Broker Patterns from the 
following developer works articles: 

► http : //www. i bm.com/devel operworks/wi ki s/di spl ay/esbpatterns/ 

► http : //www. i bm.com/ devel operworks/1 i brary/ws-enterpri seconnecti vi typatterns/i n 
dex.html 

► http : //www. i bm.com/devel operworks/websphere/1 i brary/techarti cl es/0910_phi 1 1 i i p 
s/0910_phi 11 ips.html 
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2.2.7 Microsoft Visual Studio 2010 integration 

The Message Broker Toolkit integrates with Microsoft Visual Studio 2010 for developing 
applications that use the .NET Common Language Runtime either from ESQL procedures or 
from a .NETCompute node. 

The Message Broker Toolkit integrates the ability to rapidly open Visual Studio solutions that 
are associated with .NETCompute nodes by simply double-clicking the node. The Visual 
Studio debugger can also be attached to the broker execution group process and used in 
conjunction with the broker debugger to perform step-through debugging of flows and code. 
The Message Broker Toolkit also allows you to drag and drop DLLs associated with Visual 
Studio solutions onto the message flow to create a .NETCompute node configured for the 
solution. 


2.3 Connectivity options 

WebSphere Message Broker provides support for a variety of messaging transport protocols. 
These protocols include WebSphere MQ, Java Message Service (JMS), WebSphere 
MQ/JMS, SOAP-based Web services, HTTP and HTTPS, File and Managed File Transfer, 
Java Connector Architecture (JCA) adapters for SAP, Siebel and PeopleSoft, TCP/IP, and 
Service Component Architecture (SCA). 

In this section, we introduce the various transport protocols that WebSphere Message Broker 
supports. The appropriate connection points are described for each transport type that client 
applications can use to both send messages to and receive messages from the WebSphere 
Message Broker. 


2.3.1 WebSphere MQ 

The WebSphere MQ Enterprise Transport supports WebSphere MQ applications that 
connect to WebSphere Message Broker to benefit from message routing and transformation 
options. 

The WebSphere MQ nodes put and get messages from the queue manager that is 
associated with the broker that is running the flow. If you need to read or write messages from 
other queue managers, use WebSphere MQ configuration to connect the queue managers 
and move messages over the WebSphere MQ Enterprise Transport. You can also configure 
the JMS nodes to use WebSphere MQ as a JMS provider and use a client connection to a 
remote queue manager. 

MQInput and MQGet nodes 

Use the MQInput node if the messages arrive at the broker on a WebSphere MQ queue and 
the node is to be at the start of a message flow. 

Use the MQGet node to retrieve a message from a WebSphere MQ queue, if you intend to 
get the message after the start of the message flow. 

MQOutput and MQReply nodes 

Use the MQOutput node if the target application expects to receive messages on a 
WebSphere MQ queue. 

Use the MQReply node if the target application expects to receive messages on the 
WebSphere MQ reply-to queue that is specified in the input message MQMD. 
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Figure 2-4 shows a sample message flow that makes use of the MQInput, MQGet, MQReply, 
and MQOutput nodes. 



For additional information about configuring and using each of the WebSphere MQ nodes, go 
to the WebSphere Message Broker Information Center at: 

http : //publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/i ndex. jsp 

In the WebSphere Message Broker Information Center, refer to the following topics: 

► MQInput node (ac04560_) 

► MQGet node (ac20806_) 

► MQOutput node (ac04570_) 

► MQReply node (ac04580_) 


2.3.2 Java Message Service (JMS) 1.1 

The WebSphere Message Broker JMS Transport sends and receives JMS messages using 
destinations that are accessible through a JMS provider. The built-in JMS nodes act as JMS 
clients. 

The JMS nodes work with WebSphere MQ JMS provider, WebSphere Application Server (V6 
and subsequent) service integration bus, and any other JMS provider that conforms to the 
Java Message Service Specification VI .1 . WebSphere Message Broker supports Java 6 
(Version 1 .6), so the JMS provider classes must be compliant with that version. 

JMSInput node 

Use the JMSInput node if a JMS application sends the messages. The JMSInput node acts 
as a JMS message consumer and can receive all six message types that are defined in the 
JMS Specification VI. 1. 

JMSOutput and JMSReply nodes 

Use the JMSOutput node, if the messages are for a JMS destination. The JMSOutput node 
acts as a JMS message producer and can publish all six message types that are defined in 
the JMS Specification VI .1 . 

The JMSReply node has a similar function to the JMSOutput node, but the JMSReply node 
sends JMS messages to only the reply destination that is supplied in the JMSReplyTo header 
field of the JMS message tree. Use the JMSReply node to treat a JMS message that is 
produced from a message flow as a reply to a JMS input message and when you have no 
other routing requirements. 

For additional information about configuring and using each of the JMS nodes, go to the 
WebSphere Message Broker Information Center at: 

http: //publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/i ndex. jsp 
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In the WebSphere Message Broker Information Center, refer to the following topics: 

► JMSInput node (ac24820_) 

► JMSOutput node (ac24830_) 

► JMSReply node (ac37130_) 


2.3.3 WebSphere MQ/JMS 

WebSphere Message Broker provides support that includes the ability to transform MQ 
messages to JMS and vice versa. 

WebSphere Message Broker can receive messages that have a WebSphere MQ JMS 
provider message tree format and transform them into a format that is compatible with 
messages that are to be sent to a JMS client application. 

Conversely, WebSphere Message Broker can transform a message with a JMS message tree 
structure into a message that is compatible with the format of messages that are produced by 
the WebSphere MQ JMS provider. 

MQJMSTransform node 

Use the MQJMSTransform node if the input message is of the WebSphere MQ JMS provider 
format and the output message is to be sent to a JMS client application. 

Figure 2-5 shows a sample message flow, which takes an MQ input message, transforms the 
message using the MQJMSTransform node, and outputs a JMS message. 
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Figure 2-5 The MQJMSTransform node 
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JMSMQTransform node 

Use the JMSMQTransform node if the input message is a JMS message and the output 
message must be in the format of messages that are produced by the WebSphere MQ JMS 
provider. 

Figure 2-6 shows a sample message flow, which takes a JMS input message, transforms the 
message using the JMSMQTransform node, and outputs an MQ message. 


1 E 

b 

I> ►D- 

gijL 

□ 


\ . „ 


□ 

J JMS 

[> 

M \W\ 

I> ►O 


) N=: 

H 



JMSInput JMSMQTransform Compute fMOQutputl 


Figure 2-6 The JMSMQTransform node 

For additional information about configuring and using each of the JMSMQ/MQJMS 
Transform nodes, go to the WebSphere Message Broker Information Center at: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp 

In the WebSphere Message Broker Information Center, refer to the following topics: 

► MQJMSTransform node (ac24850_) 

► JMSMQTransform node (ac24840_) 
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2.3.4 SOAP-based web services 


The WebSphere Message Broker Web services support includes provider and consumer 
scenarios, WS-Security and WS-Addressing support, and integration with DataPower 
appliances for Web service security. The standards that are supported include SOAP 1 .1/1 .2, 
WSDL 1.1, MTOM/XOP, SOAP with Attachments, and are Basic Profile 1.1 compliant. 

Integrated support for WebSphere Service Registry and Repository (WSRR) is also provided. 
Message flows can access, use, and select specific service registry entities dynamically at 
runtime. 

SOAP input and request nodes 

The SOAPInput, SOAPRequest, and SOAPAsyncRequest nodes can be used to process 
client SOAP messages and to configure the message flow to behave like a SOAP Web 
Services provider. 

The SOAPInput node processes client SOAP messages, thereby enabling the broker to be a 
SOAP Web Services provider. It is typically used in conjunction with the SOAPReply node. 

The SOAPRequest node sends a SOAP request to a remote Web service. The node is a 
synchronous request and response node and blocks after sending the request until the 
response is received. 

The SOAPAsyncRequest node sends a Web services request, but the node does not wait for 
the associated Web service response to be received. It does, however, wait for the HTTP 202 
acknowledgment before continuing with the message flow and blocks if the acknowledgement 
is not received. The SOAPAsyncRequest node is used with the SOAPAsyncResponse node 
to construct a pair of message flows that call a Web service asynchronously. 

SOAP reply and response nodes 

The SOAPReply node is used if the target application expects to receive SOAP messages in 
response to a message that is sent to the SOAPInput node. 

The SOAPAsyncResponse node is used to deliver a SOAP message in response to a 
message that is received by the SOAPAsyncRequest node. 

Figure 2-7 shows a sample Web Service Provider message flow, which makes use of the 
SOAPInput and SOAPReply nodes. 
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Figure 2-7 SOAP Web Service Provider message flow 

Figure 2-8 shows a sample Web Service Consumer message flow, which makes use of the 
SOAPRequest node. 



Figure 2-8 SOAP Web Service Consumer message flow 
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Figure 2-9 shows a sample Asynchronous Consumer message flow, which makes use of the 
SOAPAsyncRequest and SOAPAsyncResponse nodes. 
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Figure 2-9 SOAP Asynchronous Consumer message flow 

For additional information about configuring and using each of the SOAP nodes, go to the 
WebSphere Message Broker Information Center at: 

http : //publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/i ndex. jsp 

In the WebSphere Message Broker Information Center, refer to these topics: 

► SOAPInput node (ac56170_) 

► SOAPRequest node (ac56190_) 

► SOAPAsyncRequest node (ac56200_) 

► SOAPReply (ac56180_) 

► SOAPAsyncResponse (ac56210_) 

2.3.5 HTTP and HTTPS 

The WebSphere Message Broker HTTP Transport connects applications that use the HTTP 
protocol. Message flows can use the HTTP transport to work with SOAP-based Web 
services, other Web services standards, such as REST or XML-RPC, and general HTTP 
messaging, where the payload might or might not be XML. 

In the case of SOAP-based Web services, several advantages exist if you use the SOAP 
domain instead of the HTTP transport nodes. Using the SOAP domain and nodes provides 
the following advantages: 

► Support for WS-Addressing, WS-Security, and SOAP headers 

► A common SOAP logical tree format that is independent of the actual bitstream 

► Run time checking against WSDL 

HTTP input and request nodes 

The HTTPInput node receives an HTTP message from an HTTP client for processing by a 
message flow. If you include an HTTPInput node in a message flow, you must either include 
an HTTPReply node in the same flow or pass the message to another flow that includes an 
HTTPReply node. 

The HTTPRequest node interacts with a web service using all, or part, of the input message 
as the request that is sent to that service. This node can be used in a message flow that does 
or does not contain an HTTPInput or HTTPReply node. The HTTPRequest node is 
synchronous, which means it will wait until the HTTP service being contacted returns a reply. 

If you use the HTTPInput node with the HTTPReply and HTTPRequest nodes, the broker can 
act as an intermediary for web services. Web service requests can also be transformed and 
routed in the same way as other message formats that WebSphere Message Broker 
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supports. Web service requests can be received either in standard HTTP (1 .0 or 1 .1 ) format 
or in HTTP over SSL (HTTPS) format. You can select the Use HTTPS property to handle 
either HTTP or HTTPS requests. 

HTTPReply node 

The HTTPReply node returns a response from the message flow to an HTTP client. This 
node generates the response to an HTTP client from which the input message was received 
by the HTTPInput node and waits for the confirmation that it was sent. 

Figure 2-10 shows a sample Web Service Provider message flow, which makes use of the 
HTTPInput and HTTPReply nodes. 



Figure 2-10 HTTP Web Service Provider message flow 

Figure 2-1 1 shows a sample web service consumer message flow, which makes use of the 
HTTPRequest node. 
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Figure 2-11 HTTP web service consumer message flow 

For additional information about configuring and using each of the HTTP nodes, visit the 
WebSphere Message Broker Information Center at: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp 

In the WebSphere Message Broker Information Center, refer to these topics: 

► HTTPInput node (ac04565_) 

► HTTPRequest node (ac04595_) 

► HTTPReply node (ac04585_) 


2.3.6 File 


File processing support, including FTP and SFTP, is delivered through built-in nodes. This 
support allows large files to be handled without using excessive storage. It provides 
comprehensive support for record detection and sophisticated record identification that allows 
specific records to be identified in a larger flow. All of the file nodes that act as Input nodes 
provide functionality to propagate individual records as new messages based on message 
model, fixed delimiters, or fixed length information. All of the file nodes that act as output 
nodes can assemble individual records into a complete file before file transfer is performed. 

Filelnput node 

The Filelnput node can be used in any message flow that must accept messages in files. One 
or more messages can be read from a single file, and each message is propagated as a 
separate flow transaction. A file can be a single record or a series of records. 

Select FTP ->• Transfer protocol property to choose either FTP or SFTP. 
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In version 8, the Filelnput node has increased ability to work with files located in 
subdirectories, so it can process files from different senders based on the subdirectory. 
However, each Filelnput node can only be associated with one top-level directory. If multiple 
business partners are expected to submit data, it must all be delivered into folders that have a 
common root path. 

FileOutput node 

The FileOutput node can be used to write messages to files. The node writes files as a 
sequence of one or more records. Each record is generated from a single message that is 
received on the in terminal of the node. The FileOutput node will create a file in an identified 
location on the broker runtime’s file system. It can be configured to then move the file to a 
remote location using FTP or SFTP. 

A sample file transport message flow has a Filelnput node connected to a FileOutput node. 
The Filelnput node monitors the input directory and sends the data to a FileOutput node that 
writes the file to the output directory. 

FTEInput node 

The FTEInput node acts as a destination agent endpoint for files sent over the WebSphere 
MQ File Transfer Edition protocol. The FTEInput will receive files from any file transfer agent 
across the entire file transfer network. 

FTEOutput node 

The FTEOutput node acts as a source agent endpoint for files that are sent over the 
WebSphere MQ File Transfer Edition protocol. The FTEOutput node will output data to any 
file transfer agent across the entire file transfer network based on the destination information 
configured in the node properties or by the message flow logic. 

CDInput node 

The CDInput node acts as a receiving endpoint for files sent using IBM Sterling Connect: 
Direct. The node is configured to know the location of a specific Connect:Direct server. The 
node can be configured to process all of the files or a subset of the files transferred to that 
server based on the directory and file name. 

CDOutput node 

The CDOutput node acts as a sending endpoint for files that are sent using IBM Sterling 
Connect:Direct. The CDOutput node is configured to know the location of a Primary 
Connect: Direct server (PNODE in Connect: Direct terminology) and a Secondary 
Connect:Direct server (SNODE in Connect:Direct terminology). The primary server will 
receive the file data from the CDOutput node and then transfer it to the secondary server 
using Connect:Direct file transfer services. 

For additional information about configuring and using each of the file nodes, go to the 
WebSphere Message Broker Information Center at: 

http : //publ i b . boul der . i bm. com/i nfocenter/wmbhel p/v8r0m0/i ndex . j sp 

In the WebSphere Message Broker Information Center, refer to these topics: 

► Filelnput node (ac55150_) 

► FileOutput node (ac55160_) 

► FTEInput node(bc34034_) 

► FTEOutput node(bc34030_) 

► CDInput node(bc14020_) 

► CDOutput node(bc1 401 5_) 
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2.3.7 Java Connector Architecture (JCA) Adapters and WebSphere adapters 


The WebSphere Adapters nodes can be used to communicate with enterprise information 
systems (EIS). WebSphere Message Broker provides message flow nodes that support 
connectivity with the SAP, Siebel, JDEdwards and PeopleSoft adapters. 

Enterprise Metadata Discovery (EMD) is used for key data structure discovery and 
accelerated message set generation. The WebSphere Adapters nodes need an adapter 
component to access the EIS. A license for the adapter components is required. 

The WebSphere Adapters nodes can be used to interact with the Enterprise Information 
System. The SAP, Siebel, JDEdwards, and PeopleSoft adapters are supported by the 
following message flow nodes in WebSphere Message Broker: 

► SAPInput node 

► SAPReply node 

► SAPRequest node 

► Siebellnput node 

► SiebelRequest node 

► PeopleSoftlnput node 

► PeopleSoftRequest node 

► JDEdwardsInput node 

► JDEdwardsRequest node 

The WebSphere Adapters’ input nodes monitor an EIS for a particular event. When that event 
occurs, business objects are sent to the input node. The input nodes construct a tree 
representation of the business object, which the rest of the message flow can use. 

The WebSphere Adapters’ request nodes can send and receive business data. They request 
information from an EIS and propagate the data to the rest of the message flow. 

For additional information about configuring and using each of the WebSphere Adapters 
nodes, go to the WebSphere Message Broker Information Center at: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp 

In the WebSphere Message Broker Information Center, refer to these topics: 

► SAPInput node (ac37290_) 

► SAPReply node (bc22000_) 

► SAPRequest node (ac37300_)) 

► Siebellnput node (ac37310_) 

► SiebelRequest node (ac37320_) 

► PeopleSoftlnput node (ac37330_) 

► PeopleSoftRequest node (ac37340_) 

► JDEdwardsInput node (bc22690_) 

► JDEdwardsRequest node (bc22700_) 

2.3.8 TCP/IP 

WebSphere Message Broker provides support for TCP/IP connectivity of existing applications 
that use raw TCP/IP sockets for transferring data. 

TCP/IP Client nodes 

The TCPIPCIientlnput node can be used to create a client connection to a raw TCP/IP socket 
and to retrieve data over that connection. 
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The TCPIPCIientOutput node can be used to create a client connection to a raw TCP/IP 
socket and to send data over that connection to an external application. 

The TCPIPCIientReceive node can be used to receive data over a client TCP/IP connection. 

TCP/IP Server nodes 

The TCPIPServerlnput node can be used to create a server connection to a raw TCP/IP 
socket and to retrieve data over that connection. 

The TCPIPServerOutput node can be used to create a server connection to a raw TCP/IP 
socket and to send data over that connection to an external application. 

The TCPIPServerReceive node can be used to receive data over a server TCP/IP 
connection. 

For additional information about configuring and using each of the TCP/IP nodes, go to the 
WebSphere Message Broker Information Center at: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp 

In the WebSphere Message Broker Information Center, refer to these topics: 

► TCPIPCIientlnput node (ac67300_) 

► TCPIPCIientOutput node (ac67310_) 

► TCPIPCIientReceive node (ac67320_) 

► TCPIPServerlnput node (ac67330_) 

► TCPIPServerOutput node (ac67340_) 

► TCPIPServerReceive node (ac67350_) 


2.3.9 Service Component Architecture 

Service Component Architecture (SCA) simplifies creating and integrating SOA business 
applications by separating the business logic from its implementation, thus using the 
developer to focus on assembling an integrated application without knowing the details of its 
implementation. 

WebSphere Message Broker provides built-in message flow nodes that support 
interoperability with WebSphere Process Server. The SCA nodes support inbound and 
outbound scenarios with WebSphere Process Server and WebSphere Enterprise Service 
Bus. 

The nodes are configured by a Broker SCA definition.The Broker SCA Definition wizard 
creates a Broker SCA definition that includes objects that define the binding, interface, and 
message format information to permit interoperation between WebSphere Message Broker 
and WebSphere Process Server. 

SCAInput node 

The SCAInput node listens for SCA inbound requests from WebSphere Process Server to 
WebSphere Message Broker. 

SCAReply node 

The SCAReply node is used to send a message from the broker to the originating client in 
response to a message that a SCAInput node receives. 
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SCARequest node 

The SCARequest node is used to send a request to WebSphere Process Server. The node is 
configured using a Broker SCA Definition (.outsca) file. Depending on the contents of 
the.outsca file, requests can be either of the following types: 

► Two-way, synchronous: The node sends the request and then blocks until it receives a 
response or the time out period is exceeded. 

► One-way: The node sends a request only. 

SCAAsyncRequest node 

The SCAAsyncRequest node is used to send an SCA outbound request to a service 
component that runs in WebSphere Process Server. 

SCAAsyncResponse node 

The SCAAsyncResponse node receives the response from a business process that is 
running in WebSphere Process Server and to which the previous asynchronous request was 
made. The SCAAsyncResponse node can be in the same message flow or in a separate 
message flow. 

For additional information about configuring and using each of the SCA nodes, go to the 
WebSphere Message Broker Information Center at: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp 

In the WebSphere Message Broker Information Center, refer to these topics: 

► SCAInput node (ac68510_) 

► SCAReply node (ac68520_) 

► SCARequest (bc34002_) 

► SCAAsyncRequest (ac68530_) 

► SCAAsyncResponse (ac68540_) 


2.4 Transformation interfaces 

The most significant function of Message Broker is its wide range of transformation interfaces 
that open it to act as a robust data transformation engine. Data in messages received by input 
nodes are parsed into a logical message tree that works with code. Together the tree and 
code can alter the values and location of individual fields without having to know anything 
about the physical representation of the data in the message. This powerful concept shifts an 
application rapidly from receiving data through an MQInput node to receive data over HTTP 
using an HTTPInput node without any significant changes to business logic. 


2.4.1 Compute node 

The Compute node allows for the creation, editing, and execution of transformation logic 
written in the ESQL language. ESQL is a simplified language that supports the full range of 
broker function and is easy to write and easy to read. 

Message data is accessed using a dot-notation path structure that is built up of the names of 
the fields in the message tree. Individual parsers provide named constants to indicate data 
that has a special meaning with the parser structure, for example, namespace declarations in 
XML data. 
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ESQL code is stored in text files with the file extension of .esql. The Message Broker Toolkit 
provides a full featured code editor with content assist, error identification, and flagging along 
with full step-through debugger support. An ESQL stub file for holding message flow logic can 
be simply created by double-clicking a Compute node that was added to a message flow. 
The same ESQL file can contain logic associated with more than one Compute node, and 
ESQL files can load and reference other ESQL files as code libraries. ESQL also supports a 
schema syntax that allows for separation of function into logical namespaces. This supports 
the same modular development of code and methods as other full-featured programming 
languages, such as Java, PHP, and .NET CLR languages. ESQL can natively invoke 
functions that are coded in Java, .NET, and in database stored procedures. 

ESQL is compiled into an internal representation and deployed to the Broker as part of an 
application or library. ESQL files can also be deployed individually to an application or library, 
including as stand-alone files in the default application. 


2.4.2 JavaCompute node 

The JavaCompute node allows for the creation, editing, and execution of transformation logic 
that is written in the Java language. Java is a full functioning programming language that 
supports an object-oriented development model and is widely used for applications of all 
kinds across all levels and areas of business. 

WebSphere Message Broker provides a full featured set of Java classes that present an 
object-oriented view onto the logical message tree giving a Java programmer the ability to 
develop WebSphere Message Broker solutions with a minimum of additional training. The 
Java API and class library for the broker supports full control over the logical message tree. 
The JavaCompute node can be used for integrating with applications and other endpoints that 
are not using transports available with the built in nodes. The JavaCompute node also can 
reuse existing Java code that performs business logic. 

The Message Broker Toolkit provides a full-featured Java development environment based on 
the Eclipse tooling. This environment includes content assist, debugging aids, error marking, 
and the creation of stub classes and methods. The same Java classes can be used by 
multiple JavaCompute nodes, and Java objects can be shared across Java code running in 
the same execution group. 

Java code is compiled into jar files and deployed as part of an application or library through 
the normal broker deployment tooling. The Java code can be manually deployed to the 
broker’s file system and made available using a JavaClassloader Configurable Service. Java 
code runs inside a Java Virtual Machine that is part of each individual execution group 
process. 


2.4.3 PHPCompute node 

The PHPCompute node opens the creation, editing, and execution of transformation logic 
written in the PHP language. PHP is a full-functioning programming language that supports 
an object-oriented development model. PHP also allows a script-like programming model that 
does not require an object-oriented approach. PHP is widely used for web-based applications 
and in development environments where simplified programming models are important. 

WebSphere Message Broker provides a full-featured PHP API and set of classes that present 
an object-oriented view onto the logical message tree. The PHP API in the broker provides a 
convenient path navigation mechanism that is natural to the way that data is accessed by 
PHP code. The PHPCompute node can be used to integrate with applications and endpoints 
using transports that are not fully supported by WebSphere Message Broker built in nodes, 
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and existing PHP code can be reused. The PHPCompute node can call the evaluate method 
of a PHP class or it can invoke a stand-alone PHP script file that returns a modified message 
tree. 

The Message Broker Toolkit does not provide immediate support for PHP code editing; 
however, Eclipse-based tooling can be installed into the Message Broker Toolkit environment. 
Message Broker Toolkit also does not support step-through debugging of PHP code. 

PHP code is compiled into Java bytecodes and deployed into an application or library. It is 
executed in the execution group JVM. 


2.4.4 .NETCompute node 

The .NETCompute node allows for creating, editing, and executing of transformation logic in 
any of the programming languages supported by the Microsoft Common Language Runtime 
at version 4.0. This includes Visual Basic, C#, JScript, F#, and more than 40 other 
programming languages. 

The .NETCompute node can only be deployed to a broker that is running on a Windows 
platform. 

The .NETCompute node allows for simple and fast integration with Visual Studio, which is the 
main development environment for .NET code outside of WebSphere Message Broker. The 
broker leverages this power and ease of use to provide a common development environment. 
Code is created, edited, compiled, and debugged using Visual Studio. The .NETCompute 
node holds a reference to the location of compiled code and the broker runtime loads the 
assemblies and executes the code. 

WebSphere Message Broker provides a full featured .NET API and set of classes that 
represents an object-oriented view on the logical message tree. This is similar to the Java and 
PHP APIs, however the .NET library provides several additional helper classes and some 
additional simplified ways to access the logical message tree. The .NET API can use the 
Microsoft LINQ APIs to query the tree and interact with the results, and provide a 
comprehensive path navigation mechanism that is natural to the way data and objects are 
accessed in .NET Code. Because the .NET API is built against the Common Language 
Runtime, full support for these features exists in all programming languages that work with the 
CLR V4. 

WebSphere Message Broker includes project templates that are installed into Visual Studio, 
making it easy to write .NET code to perform logic inside the broker. The Visual Studio 
Debugger also allows for the step-through of .NET code that is deployed inside the broker. 
This supports comprehensive debugging in a development environment. 

Scenarios in this IBM Redbooks Publication focus on several important aspects of writing 
.NET code that is used by the .NETCompute node to access external systems and transform 
or interpret message data. 


2.5 Administering WebSphere Message Broker 

In this section, we provide an introduction to administering WebSphere Message Broker. We 
cover WebSphere Message Broker Explorer, broker sets, and aspects of web administration 
console ad the functions of record and replay. 
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2.5.1 WebSphere Message Broker Explorer 


The WebSphere Message Broker Explorer is a tool for administrators and provides the 
capability for enhanced WebSphere Message Broker monitoring and management. 

WebSphere Message Broker Explorer is installed as a plug-in for WebSphere MQ Explorer. 
The Brokers view is added to the WebSphere MQ Explorer Navigator pane. The broker 
administration tasks can then be performed from this Brokers view. 

Using the WebSphere Message Broker Explorer, as shown in Figure 2-12, the user can 
administer their brokers and WebSphere MQ queue managers, in the same tool. 



Figure 2-12 WebSphere Message Broker Explorer 


Additionally, the new WebSphere Message Broker Explorer provides the following new 
capabilities: 

► Create, delete, start, and stop local brokers without using the command line. 

► Show the relationships between the brokers and queue managers. 

► Deploy a broker archive file to multiple execution groups in one step. 

► Visualize a brokers accounting and statistics data. 

► Configure broker properties, including creating and modifying services for broker 
communication with external services, such as SMTP, JMS providers, and adapters. 
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► View the broker administration queue and remove pending tasks that were submitted to 
the broker. 

► Connect and configure DataPower security settings. 

► View the Administration Log showing all activity that occurred on a given broker. 

The WebSphere Message Broker Explorer also provides a number of QuickViews that you 
can use to view the properties of brokers and their resources. These views are automatically 
displayed in the Brokers folder in the WebSphere MQ Explorer Navigator view. There is also a 
QuickView for viewing the details of broker archive files that are imported into the WebSphere 
Message Broker Explorer. 


2.5.2 Broker sets 

You can use a broker set to visually group your brokers in the WebSphere Message Broker 
Explorer. If you have a large number of brokers displayed, it might be helpful to group the 
brokers using broker sets. Use broker sets to separate the development, test, QA, and 
production brokers into logical groups. You can create manual broker sets, automatic broker 
sets, or a combination of both. 

A manual broker set is empty until you add brokers to the broker set from th eAll broker set or 
another broker set. You can add or remove brokers from the manual broker set at any time. 

An automatic broker set uses broker tags to dynamically add and remove brokers from a set 
that is based on values that you provide or the current state of brokers. 


2.5.3 Web Administration and record and replay 

WebSphere Message Broker V8 also comes with a web-based administrative console that 
provides a read-only view into the broker runtime environment. The console can also be used 
as an end-user console for the record and replay functions for messages that pass through 
the Message Broker. The record and replay functions allow a broker to store copies of 
messages that are passed through the system into a database and then the web 
administration console can be used to retrieve and resend the needed messages. 

This function must be specifically enabled by the broker administrators to work. Figure 2-13 
on page 32 shows the web administration console. 


Chapter 2. Introduction to WebSphere Message Broker V8 31 




Figure 2-13 WebSphere Message Broker web administration console 

The web administration console also exposes a full REST API for accessing resources and 
performing record or replay features. These functions can then be easily integrated into 
existing or custom applications. 

In addition to the WebSphere Message Broker Explorer and the read-only web administration 
console, there are command-line and API-based utilities that you can use to accomplish 
broker administration tasks. For example, the CMP API Exerciser sample that WebSphere 
Message Broker provides utilizes the Java Administration API. You can use the CMP API 
Exerciser to view and manage brokers and their execution groups. You can also use it to 
create, modify, and delete services that can be configured and general broker administration 
tasks. 

The Java Administration API is also available to users for scripting broker administration 
tasks. 
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2.6 Deploying applications 


WebSphere Message Broker applications and libraries contain message flows and the 
message models that are used to describe the data used by message flows. Applications and 
libraries are independently deployable containers. An application can contain other libraries. 
WebSphere Message Broker resources can be deployed to the execution groups of the 
brokers by first adding the application or library to a broker archive file (bar file) and then 
deploying the bar file to the broker’s execution group. You can deploy the bar files using the 
command line or with the Message Broker Toolkit. 

You can create a bar file using a graphical interface in the Message Broker Toolkit. The 
interface allows you to select the components to include for deployment. If properties, such as 
queue names or other configurable properties, are promoted to the bar level, the broker 
archive editor offers options to configure these properties. 

For more information about promoted properties, see the WebSphere Message Broker online 
help system at: 

http://publib.boulder.ibm.eom/infocenter/wmbhelp/v8r0m0/topic/com.ibm.etools.mft.d 

oc/ac00640_.htm 

The bar file can also be deployed to the broker’s execution group using a command line 
interface. The corresponding command is mqsideploy. For more information, search for the 
mqsi deploy command topic in the WebSphere Message Broker Information Center at: 

http : //publ i b . boul der . i bm. com/i nfocenter/wmbhel p/v8r0m0/topi c/ 
com. i bm.etool s.mft .doc/an09020_.htm 

You can also deploy a bar file using WebSphere Message Broker Explorer. Drag and drop the 
bar file from the Broker Archive Files folder to the execution group. The WebSphere Message 
Broker Explorer also supports customizing bar files using overrides and promoted properties. 

You can also develop an application written in Java that uses the Administration API to deploy 
bar files. 


Deploying resources without creating a BAR file: The Message Broker Toolkit allows 
you to deploy a message flow, application, or library directly by dragging it to an execution 
group (without creating a BAR file). In this case, the dependent resources are deployed 
too. 


2.7 Getting started 

As you read through the scenarios, you will encounter instructions for performing tasks in the 
Message Broker Toolkit. These instructions center on creating and deploying message flows. 
This section provides the information needed to perform these tasks. 
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2.7.1 Opening the Message Broker Toolkit 


The Message Broker Toolkit is used to develop and deploy message flows and to manage 
brokers. It is supported on Windows and Linux on x86. The scenarios in this book all use 
Message Broker Toolkit installed on a Windows system: 

1 . Open the Message Broker Toolkit. In a default installation, this can be done by selecting 

Start All Programs IBM WebSphere Message Broker Toolkit IBM WebSphere 
Message Broker Toolkit 8.0 ->• WebSphere Message Broker Toolkit 8.0. 

2. In the Workspace Launcher dialog, enter a location for your workspace in the Workspace 
field, and press OK, as shown in Figure 2-14. 



Figure 2-14 Creating a new workspace 

3. The IBM WebSphere Message Broker Welcome window will then display. Click Go to the 
Message Broker Toolkit, as shown in Figure 2-15. 


Go to the Message Broker Toolkit 



Figure 2- 15 Go to Message Broker Toolkit 


You are now in the Broker Application Development perspective with an empty workspace 
ready for new projects to be added and created (shown in Figure 2-16 on page 35). 
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Figure 2-16 Empty workspace in the Broker Application Development perspective 


2.7.2 Creating a new application 

Use the following procedure to quickly outline how to create a new application. These easy 
steps create efficiency, accuracy, and help standardize the process: 

1 . There are several ways to start the New Application wizard: 

- Select New Application, Figure 2-16 (see in the Broker Development view if this 
option is available). 

- Select File -» New -» Application. 

- Right-click in an empty area of the Broker Development view and select New 

Application. 

Any of these actions will start the New Application wizard. 

2. Name the application, and click Finish (see Figure 2-17 on page 36). 
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Figure 2-17 New Application wizard 

The new application will appear in the Broker Development view (see Figure 2-18). 



Figure 2-18 A new application 


2.7.3 Creating a new message flow 

Message flows contain the logic of the application. To create a new message flow in the 
application follow these steps: 

1 . The following list shows several ways to start the New Message Flow wizard: 

- Click New, under the application name, as shown in Figure 2-18, and select Message 
Flow. 

- Select File New Message Flow. 

- Right click in an empty area of the Broker Development view and select New -» 

Message Flow. 

2. In the Container field, enter the application name. Enter a name for the new message flow 
and click Finish, as shown in Figure 2-19 on page 37. 
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Figure 2-19 Create a new message flow 

3. The new message flow is created and opened in the Message Flow editor, as shown in 
Figure 2-20. 
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Figure 2-20 New message flow opened in the Message Flow editor 


4. A message flow is built by dragging nodes from the Palette to the canvas, setting the 
properties for the nodes, and wiring them together to form a flow for messages to traverse. 
Each drawer in the Palette can be opened by clicking it, to show the nodes in that drawer. 
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In Figure 2-21, the HTTPInput node and .NETCompute node were dragged from the 
Palette located to the left over to the canvas located to the right. The HTTPInput node is 
selected in the canvas, and its properties are displayed. The Properties view has multiple 
tabs to the left that allow you to update the properties by category, for example, input 
message parsing options. 

The out terminal of the HTTPInput node was wired to the in terminal of the .NETCompute 
node. A wire is created by clicking the terminal of one node, and then dragging the 
connection to the input node of another terminal. 
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Figure 2-21 The HTTPInput node selected within the canvas and properties opened 


5. To save the message flow, click CTRL-S, or select File Save. 

2.7.4 Creating a broker 

A broker can be created from the Message Broker Toolkit, the WebSphere Message Broker 
Explorer or when using the WebSphere Message Broker mqsi createbroker command. 

Using the Message Broker Toolkit 

Brokers can be created, deleted, and managed from the Message Broker Toolkit. To create a 
broker: 

1 . Open the Message Broker Toolkit. 

2. In the Brokers view, right-click Brokers, and select New -» Local Broker, as shown in 
Figure 2-22 on page 39. 
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Figure 2-22 Creating a new local broker in the Brokers view 

3. Enter a name for the broker. Enter an existing queue manager or a new name for the 
broker queue manager. Finally, enter the execution group name. Click Finish. This prompt 
is shown in Figure 2-23. 
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Figure 2-23 Entering names for broker, queue manager, and execution group 
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4. The broker and queue manager are created. The results are shown in the Progress 
Information window. Click Close. See an example of the results window in Figure 2-24. 



Figure 2-24 Update bar reflecting successful completion 

The new broker and execution group will be started and will appear in the list of brokers. 

Using the WebSphere Message Broker Explorer 

Brokers can be created, deleted, and managed from the WebSphere Message Broker 
Explorer. Follow these steps to create a broker: 

1 . Open the WebSphere Message Broker Explorer by right-clicking the WebSphere MQ 
icon in the Windows system tray and selecting WebSphere Message Broker Explorer. 
See Figure 2-25 for an example. 
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Figure 2-25 Open the WebSphere Message Broker Explorer 
2. Right-click Brokers, and select New ->• Local Broker, as shown in Figure 2-26. 
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Figure 2-26 Creating a Local Broker 


3. Enter a name for the new broker, and click Next, as shown in Figure 2-27 on page 41 . 
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Figure 2-27 Name the new broker 


4. Enter the queue manager name for the broker. You can enter an existing name or a new 
name and the wizard will create the queue manager for you. You can also enter the name 
of the execution group or accept default as the name. Click Next. See Figure 2-28 on 
page 42 for an example. 
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Figure 2-28 Prompt to enter new queue manager name 


5. The new broker and queue manager is created and the results shown in the Summary 
window. Click Finish. Figure 2-29 shows an example of this window. 



Figure 2-29 Results of the Create Broker wizard 
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The new broker and execution group will be started and will appear in the list of brokers. 


Using a command 

The broker can also be created using the mqsicreatebroker command. Use the following 
syntax with basic parameters for this command: 

mqsicreatebroker brokername -i Local System -q queuemanagername 

For example, the following command creates a broker named SAMPLEBROKER and its 
queue manager SAMPLEBROKER_qmgr: 

mqsicreatebroker SAMPLEBROKER -i Local System -q SAMPLEBROKER_qmgr 
WebSphere Message Broker commands are in the Broker Install /bin directory. 

A complete list of the options for this command are available at the following address: 

http://publib.boulder.ibm.eom/infocenter/wmbhelp/v8r0m0/topic/com.ibm.etools.mft.d 
oc/an28125_. htm 


2.7.5 Managing brokers 

Brokers can also be managed with the Message Broker Toolkit, WebSphere Message Broker 
Explorer, and commands. The following examples show approaches for the Message Broker 
Toolkit and WebSphere Message Broker. A link is provided for managing brokers with 
commands. 

WebSphere Message Broker Toolkit 

The Brokers view in the Message Broker Toolkit lists the brokers, shows their status, and 
provides options for starting, stopping, and deleting existing brokers. 

Right-click Brokers to access options to create a new broker or connect to a remote broker, 
as shown in Figure 2-30. 



Figure 2-30 Options window for creating or connecting to a local broker 

Right click a broker to start or stop the broker, delete the broker, or to create a new execution 
group, as shown in Figure 2-31 on page 44. 


Chapter 2. Introduction to WebSphere Message Broker V8 43 




T Broker Development £3 ^ Patterns Explorer 

» H % 


Application Development 


New... 

- f5l] 5ample_Application 
S'ljjJ 1 Flows 

5ample_msgflow.msgflow 



o Brokers £3 o- Outline Data Source Explorer ^ Tasks 

0 

Q “ □ 


- ilifcg Brokers 
lj-<S BRK_ITSO 
$■■■<3 IT50BR0KER 
i-J M5MQ 


5AMPLEBROKER 


default 


Figure 2-3 1 Options menu for the local broker or creating a new execution group 

And finally, right-click an execution group to deploy artifacts to it or to stop, start, and delete it. 
The options are shown in Figure 2-32. 


&S Brokers 

Outline 1J§ Data Source Explorer 

Tasks # 13 ° □ 

B-iBg Brokers 

$-<3 BRK_ITSO 
$ ■<3 IT50BR0KI 
lj-<J M5MQ 
H -<S 5AMPLEBR.' 
^ 

ER 

DKER 

Deploy ... 



& Stop 
^ Refresh 



^ Delete ► 



^.Launch Debugger (Port is 0) 





Figure 2-32 Options menu for the execution group 


WebSphere Message Broker Explorer 

WebSphere Message Broker Explorer provides similar functions for brokers and execution 
groups. Figure 2-33 on page 45 shows the options available for brokers. 



44 


Using WebSphere Message Broker V8 in Mid-Market Environments 



fep MQ Explorer - Navigator kT\^_ Q <=[> | ^ ^ 

□ © IBM Web5pl 
S CS Queue 1 
& Queue 1 
& JMS Adi 
+1 S Manage 
IS? Service 
El 

here MQ 
Managers 
Manager Clusters 
ministered Objects 
id File Transfer 
Definition Repositories 

l T . 

€ S BR.K 
:+: $ ITS 
€ <3 Msr 
+ <3 SAP- 
+1 |2® Broker 

New 

01 

Local Broker ^ 

Connect to a Remote Broker. . . 

Connect to a Remote Broker Using *. broker File. . . 


Broker Sets ► 


Figure 2-33 Options available for brokers in WebSphere Message Broker Explorer 

Figure 2-34 shows the options for brokers that are available in WebSphere Message Broker 
Explorer. 



Figure 2-34 Options for brokers or to create a new execution group 

Figure 2-35 on page 46 shows the options available for execution groups within WebSphere 
Message Broker Explorer. 
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Figure 2-35 Execution group options 


Commands 

Brokers and execution groups can be managed using mqsi commands. For a complete list of 
commands, follow this link: 

http://publib.boulder.ibm.eom/infocenter/wmbhelp/v8r0m0/topic/com.ibm.etools.mft.d 
oc/an07060 . htm 


2.7.6 Creating a BAR file for deployment 

WebSphere Message Broker applications are contained in broker archive (BAR) files for 
deployment. To create a BAR file for deployment of the application: 

1 . Right-click the application in the Broker Development view, and select New — > BAR File. 
For an example, see Figure 2-36 on page 47. 
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Figure 2-36 Creating a new BAR file 


2. Enter a name for the BAR file, as shown in Figure 2-37, and click Finish. 



Figure 2-37 Naming the new BAR file 

3. The new BAR file opens in the Broker Archive editor with multiple tabs for configuration. 
On the Prepare tab, select the application then click the Build and Save button. This 
procedure is shown in Figure 2-38 on page 48. 
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Figure 2-38 Configuring the new BAR file 


Configurable properties: If there are configurable properties for the message flow, select 
the Manage tab, expand the application in the view, and select the message flow. The 
Properties view can then be used to configure the properties. 


Parallel processing for input nodes: The broker always creates a separate thread for 
each input node in a message flow. For example, a message flow with three input nodes 
will be processed by three threads by default. You can specify additional threads for the 
whole flow using the Additional Instances configuration parameter of the BAR file. 

To see this parameter, select the Manage tab, and select the compiled message 
(message_flow.cmf file). The setting will be in the Properties view on the Configure tab. 

These additional thread instances are distributed between input nodes on a first-come 
first-served basis. If you need more even distribution for your input nodes, you can use a 
separate thread pool for each of them. Select the pool from the Instances tab on the 
Properties view for each input node during design time. 


4. Close and save the BAR file. 


Deleting BAR files: You will notice in the Message Broker Toolkit that right-clicking a BAR 
file does not give you the option to delete it. Instead, highlight the BAR file, and press the 
delete key. 


2.7.7 Deploying the BAR file to a broker 

BAR files are deployed to execution groups by dragging and dropping from within the 
Message Broker Toolkit or the WebSphere Message Broker Explorer. 
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Figure 2-39 shows the application deployed for the default execution group in the broker. The 
broker is named, SAMPLEBROKER. 



Figure 2-39 The application is deployed within the broker (the red arrow represents a drag and drop) 


2.7.8 Executing WebSphere Message Broker commands 

WebSphere Message Broker includes a set of commands that can be used to quickly operate 
or configure a broker. The commands are located in the Broker_lnstall/ bin directory. To 
configure a broker execute these commands: 

1 . Open a command prompt. 

2. Change the directory to the Broker _Install /bin directory. 

3. Execute the mqsi prof i 1 e command to prepare the user environment for executing 
commands. 

Example 2-1 shows an example of the commands to prepare the environment. 

Example 2- 1 Executing WebSphere Message Broker commands 

c:cd \ Program Files\IBM\MQSI\8.0.0.0\bin 

C:\Program Fi les\IBM\MQSI\8.0.0.0\bi n>mqsiprofi le 

MQSI 8. 0.0.0 

C:\Program Fi 1 es\ I BM\MQS I \8. 0.0.0 


A list of commands and links to help can be found at: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp? topi c=%2Fcom.ibm 
.etool s.mft.doc%2Fan07060 .htm. 
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2.8 Creating WebSphere MQ queue managers and queues 


The WebSphere Message Broker infrastructure depends on WebSphere MQ. Brokers have a 
queue manager and queues to support them. These queue managers and queues are 
created when you create a broker. 

Message flows also can contain WebSphere MQ nodes that require a queue manager and 
queue to be defined. This section provides you two methods for creating queue managers 
and queues for use by WebSphere Message Broker. 


2.8.1 Creating queue managers 

There are two simple ways to create a queue manger. You can create the queue manager 
with a WebSphere MQ command or from the WebSphere MQ Explorer. 

2.8.2 Creating queues and queue managers using commands 

The crtmqm command creates a queue manager, for example, to create a queue manager 
named qmgrl, use the following command: 

c:\>crtmqm qmgrl 

The strmqm command can be used to start the queue manager. 
c:\>strmqm qmgrl 

Example 2-2 shows the syntax for creating and starting a queue manager. 

Example 2-2 Creating and starting a queue manager 

C : \Users\Admi ni strator>crtmqm qmgrl 
WebSphere MQ queue manager created. 

Directory 1 C:\Program Files (x86)\IBM\WebSphere MQ\qmgrs\qmgrl 1 created. 
Creating or replacing default objects for qmgrl. 

Default objects statistics : 68 created. 0 replaced. 0 failed. 

Completing setup. 

Setup completed. 

C : \Users\Admi ni strator>strmqm qmgrl 
WebSphere MQ queue manager 'qmgrl' starting. 

5 log records accessed on queue manager 'qmgrl' during the log replay phase. 

Log replay for queue manager 'qmgrl' complete. 

Transaction manager state recovered for queue manager 'qmgrl'. 

WebSphere MQ queue manager 'qmgrl' started. 


After you have an active queue manager, you can use the RUNMQSC command to issue 
commands interactively for the specified queue manager: 

1 . You will first issue the runmqsc command against the queue manager: 
c:\>runmqsc Queue Manager Name 

2. Enter the commands to execute against the queue manager. The DEFINE QLOCAL 
command can be used to create a local queue: 

DEFINE QLOCAL [queue name) 
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3. When you are done, end the session: 

END 

For an example, review the setup shown in Example 2-3. 

Example 2-3 Using the RUNMQSC command to issue commands to the queue manager 
C : \Users\Admi ni strator>runmqsc qmgrl 

5724-H72 (C) Copyright IBM Corp. 1994, 2009. ALL RIGHTS RESERVED. 
Starting MQSC for queue manager qmgrl. 

DEFINE QLOCAL(queuel) 

2 : DEFINE QLOCAL(queuel) 

AMQ8006: WebSphere MQ queue created. 

END 

3 : END 

2 MQSC commands read. 

One command has a syntax error. 

All valid MQSC commands were processed. 

C : \Users\Admi ni strator> 


For more information about the DEFINE QLOCAL command visit the following link: 

http : //publ ib. boulder. ibm.com/infocenter/wmqv7/v7r 1/topi c/com. ibm.mq. doc/sc 1 12 10_. 
htm 


2.8.3 Creating queue managers and queues from the WebSphere MQ Explorer 

Queue managers can be created in WebSphere MQ Explorer by selecting Queue Managers. 
Queue managers can be created in the Navigator view of the WebSphere MQ Explorer by 
right-clicking and selecting New -» Queue Manager. After that selection, you will enter the 
name of the queue manager, and click Finish. 

Queues can be created in the WebSphere MQ Explorer by selecting the queue manager in 
the WebSphere MQ Explorer, Navigator view, and right-clicking the Queues folder. Select 
New ->Queue, as shown in Figure 2-40. Enter the queue name, and click Finish. 
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Figure 2-40 Creating a New Queue 
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Using the tools for WebSphere 
Message Broker and .NET 
Integration 


The Microsoft Visual Studio 2010 development environment is a best of breed solution for 
developing .NET platform code. To fully use the capability of this powerful IDE development of 
.NETCompute nodes, this IBM Redbooks publication features the tight integration between 
the WebSphere Message Broker Toolkit and Visual Studio. The Message Broker Toolkit is 
where you develop the flow structure and properties, and Visual Studio is where you develop 
.NET code to run inside the WebSphere Message Broker runtime. 

This chapter takes a closer look at how you can use the Message Broker Toolkit and Microsoft 
Visual Studio to integrate .NET applications into a message flow. 


© Copyright IBM Corp. 2012. All rights reserved. 
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3.1 Creating a .NETCompute node in a message flow 


This section demonstrates how to use Message Broker Toolkit and Visual Studio together to 
develop a simple flow that counts the number of characters in an input message. 

The tasks are to create a message flow with the .NETCompute node and then to create the 
implementation code for the node using Visual Studio. 


3.1.1 Creating the messaging flow 

To create a simple message flow that includes a .NETCompute node: 

1 . Open the Message Broker Toolkit, and create a new application called CountCharsApp. 

2. Create a new message flow in the application called CountCharsFl ow. The blank message 
flow will now be open in the canvas. The message processing nodes are displayed in the 
palette to the left of the canvas. 

3. In this example, we use three nodes, the MQInput node, the MQOutput node, and the 
.NETCompute node. The function of each of these nodes, in this scenario, is defined in the 
following list: 

- MQInput node: Reads (GETs) a message from an MQ queue using the BLOB (binary) 
parser and constructs an in-memory representation of this message, which can then 
be transformed (the logical tree). 

- .NETCompute node: Runs a .NET class implemented in C# that counts the number of 
characters in the input message and creates a new output message with the total 
characters listed. 

- MQOutput node: Writes (PUTs) a message to an MQ queue with the content defined in 
the logical message tree. 

To add the nodes to the message flow follow these steps: 

a. Drag the MQInput node from the WebSphere MQ drawer of the palette onto the 
canvas. 

b. Drag the MQOutput node from the WebSphere MQ drawer of the palette onto the 
canvas 

c. Drag the .NETCompute node from the Transformation drawer of the palette onto the 
canvas. 

Arrange the message flow as shown in Figure 3-1 and described in step 4. 
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Figure 3-1 The message flow, before wiring the terminals 

4. The execution path taken by a message through the message flow is defined by wiring the 
terminals of the nodes together. In this example, the execution flow is in the following 
order: MQInput node -> .NETCompute node -» MQ Output node. 

To wire the flow: 

a. Click the Out terminal of the MQInput node, and drag the wire to the In terminal of 
the NETCompute node. 
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b. Click the Out terminal of the .NETCompute node, and drag the wire to the In 
terminal of the MQOutput node. 

The wired flow looks like the example in Figure 3-2. 
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Figure 3-2 The wired message flow 

5. The MQInput and MQOutput nodes read and write from MQ queues. The queue used by 
each node is set in the node properties: 

a. Click the MQInput node in the canvas to open the properties. Click the Basic tab, and 
enter C0UNT_IN as the queue name, as shown in Figure 3-3. 
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Figure 3-3 Setting the input queue to C0UNT_IN 


b. Click the MQOutput node in the canvas to open the properties. Click the Basic tab, 
and enter COUNTJDUT as the queue name, as shown in Figure 3-4. 
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Figure 3-4 Setting the output queue to C0UNT_0UT 


Note: Before the flow is deployed the COUNTJN and COUNT_OUT queues must be 
created on the broker’s queue manager. 
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3.1.2 Creating the code for the .NETCompute node 

To develop the .NET portion of the example, we take advantage of the tight integration 
between the Message Broker Toolkit and Visual Studio. 

During installation of WebSphere Message Broker V8, a number of wizards are added to, 
which can be used to create skeleton code for .NETCompute nodes. Skeleton code is 
available for the following common node functions: 

Creating a message This project is used when the node will create a new logical message 
tree that is not based on the input message tree. 

Filtering a message The node will not modify the message but will route it or filter it based 
on examining the content of the logical tree. 

Modifying a messageThe node will modify the input data, transforming it into a new 
structure or enriching it with new data. 


Integration steps: The templates for creating WebSphere Message Broker .NET artifacts 
are installed by default as long as the Message Broker Toolkit is installed after Visual 
Studio is installed. If Visual Studio is installed after Message Broker Toolkit, you must 
execute a specific file from the Message Broker Toolkit installation directory to install the 
Broker .NET templates. This file is called IBM. Broker. DotNet. vsix and is located in the 
wmbt subfolder of the Message Broker Toolkit install. Double-click this file and wait until it 
responds back that the templates are installed. This might not provide any visible feedback 
until the completion notice, so some patience is required. 


In this example, we create a new message tree to hold the number of characters in the 
message. 

To create a new Visual Studio project, to hold the .NET code for the .NETCompute node, 
follow these steps: 

1 . In the Message Broker Toolkit, right-click the .NETCompute node, and select Open 
Microsoft Visual Studio, as shown in Figure 3-5. Visual Studio launches automatically. 
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Figure 3-5 Opening Visual Studio 


2. Create a new Visual Studio project using the following steps: 
a. From the Visual Studio menu, select File -» New -» Project. 
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b. From the Installed Template Panel, navigate to Visual C# Message Broker. 

c. In the center pane, select Project to create a Message Broker message. 

d. Fill in a Name for your project in the Name panel, in this case, CountCharsNode. 
The completed dialog looks like the example shown in Figure 3-6. 



Figure 3-6 Creating a new Visual Studio project 

3. Click OK. The new project is created, and a new CreateNode.es class is opened in the 
editor. See Figure 3-7 on page 58 for an example. 
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CreateNode.es X | 


BBEHE 

CountCharsNode , CreateNode 

^ Evaluate(NBMessageAssembly inputAssembly) 

0 ® lE | a 


liH 

NBMessage inputMessage = in put Assembly. Mess age; 

// Create a new empty message, ensuring it is disposed after use 
using (NBMessage outputMessage = new NBMessage (}) 

{ 

NBMes sage Assembly out Assembly = new MBMessageAssemblyfinputAssembly, outputMes 
NBElement inputRoot = in putHes sage. Root Element; 

NBElement outputRoot = outputMessage , Root El ement; 

| ^ Solution 'CountCharsNode' 
□ l^l CountCharsNode 

ED Properties 

ED LSI References 
^ CreateNode.es 


// Optionally copy message headers, remove if not needed 
OopyMessageHeaders( inputRoot, outputRoot); 



#region UserCode 

// Add user code in this region to create a new output message 



#endregion UserCode 




// Change the following if not propagating message to the 'Out' terminal 
outTerminal , Propagate (outAssembly ) ; 

} 

} ■ 


100% - i\ 

1 M \ 



Figure 3-7 The new CreateNode.es class is opened in the editor automatically 


4. In WebSphere Message Broker, all .NETCompute nodes are derived from the 

NBComputeNode class. The New Project wizard will create a new class derived from 
NBComputeNode and provide a skeleton implementation of the Evaluate() method. The 
Evaluate() method is invoked each time a message is propagated to the Input terminal of 
the .NETCompute node. If the message must be propagated to any nodes connected to 
the .NETCompute node terminals, the Evaluate() method itself must propagate the 
message using the NBOutputTerminal.Propagate() method. 

The skeleton code ensures that this Propagate() method is called and provides a 
UserCode region for you to add your own code. 

Add the code shown Example 3-1 into the UserCode #region of the CreateNode.es file. 
Example 3-1 CreateNode.es UserCode 

int length = inputRoot["BLOB"] . LastChi 1 d.GetByteArrayO .Length; 

NBElement xml nscOutputEl ement = 

outputRoot . Create LastChi 1 dUsi ngNewParser("XMLNSC") ; 
NBElement xmlRoot = xml nscOutputEl ement. CreateFirstChi 1 d("Output") ; 
xml Root .CreateLastChi 1 d( "Count") .SetVal ue(l ength) ; 


This code references the BLOB parser in the input message tree and obtains its value as 
a byte array. The length of this byte array is stored in the length integer. A new XMLNSC 
parser is used to construct an XML message body for the output tree and the length filed 
is used to populate the Output/Count element. 

5. After you modify the code for the CreateNode.es file, save the file and build the project 
using the Build Build Solution menu item. This converts the code from a .cs file into a 
.NET assembly dll file which can be used by the WebSphere Message Broker runtime. 


Note: One instance of CreateNode.es is created for each copy of the node in the flow. So, 
if you are running with Additional Instances set, all threads will run against the same 
CreateNode class. 

Care must therefore be taken that the EvaluateQ method is threadsafe and reentrant. 
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The results are shown in the Output view at the bottom (you might need to switch from the 
Error List view). The output of a successful build is shown in Figure 3-8. 
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______ Build started: Project: CountCharsNode^ Configuration : Debug Any CPU ------ 
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Copying file from " r obj\Debug\CountCharsNode . pdb" to M bin\Debug\CountCharsNode . pdb' r . 

Build succeeded. 

Time Elapsed 66:66:01,, IS 

========== Build: 1 succeeded or up-to-date., B failed., B skipped ========== 


If 


ja. 


E 


Figure 3-8 Building the assembly 


3.1.3 Setting the properties for the .NETCompute node 

After the assembly is built, you must tell the .NETCompute node which assembly class it 
uses. To do this, return to the Message Broker Toolkit, and follow these steps: 

1 . Select the .NETCompute node on the canvas. 

2. In the Basic tab, enter the location of the output assembly. The assembly is at: 

location\solution_name\project_name\bi n\Debug\project_name .dl 1 

The location, project, and solution name were determined when the project was created 
(see Figure 3-6 on page 57). The output location can also be seen in the output of the 
build (see Figure 3-8). 

3. In the Class Name field, enter the name of the class, in this case, CreateNode. 

Verify that the completed dialog looks like Figure 3-9. 
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Figure 3-9 Associating the assembly with the node 
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Tip: Keep the following points in mind when you define nodes: 

► The Assembly name must include the fully qualified path. 

► The Class name must not include a .cs extension. 

► Alternatively, you can strongly name the dll and load it into the Global Assembly 
Cache, and on node properties refer to the dll from the cache. More information 
about this is at the following locations in the WebSphere Message Broker 
Information Center: 

- Identifying the .NET assembly at run time: 

http://publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/topi c/com. i bm.e 
tool s .mft . doc/bc34225_. htm 

- mqsiAssemblylnstall command: 

http://publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/topi c/com. i bm.e 
tool s .mft . doc/bn34224_. htm 


4. Save the message flow. 


Tip: There is an alternative to adding a .NETCompute node to the message flow, 
building the .NET assembly, and then updating the node properties to point to the 
assembly. If you create the .NET code first and build the solution, you can simply drag 
and drop the assembly file dll file to the message flow canvas. A .NETCompute node is 
added, and you are prompted for the class name if more than one class exists. 


3.1.4 Deploying the application 

To deploy the application to your the broker, drag the CountCharsApp icon onto an empty 
execution group in the Brokers panel of the Message Broker Toolkit, as shown in Figure 3-10. 
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Figure 3-10 Deploying the CountCharsApp application to the default execution group 
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After the application is successfully deployed, you can use the WebSphere Message Broker 
Explorer to put a test message into the COUNTJN queue by following these steps: 

1 . In the WebSphere Message Broker Explorer, navigate to the queue manager associated 
with your broker in the Navigator view and select the Queues folder. 

2. Right-click the COUNTJN queue, and select Put Test Message, as shown in 
Figure 3-11. 
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Figure 3-11 Putting a test message 


3. Type any stream of characters in the message data box, and click Put message. Click 
Close. In the example shown in Figure 3-12, we used the string 123456. 



Figure 3-12 Sending a test message 

4. Select the COUNT_OUT queue, right-click, and select Browse Messages. The Message 
Browser shows the output XML message and shows that the input message was six 
characters long, as shown in Figure 3-13. Click Close. 



Figure 3-13 Displaying the output Message 
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3.2 Hot swap deploys 


When you are developing a .NETCompute node, it is likely that as a result of testing you must 
make some changes to the code. The round trip cycle of changing the code, building the 
assembly, and redeploying to the broker can make this a time consuming process. 

To counteract this time loss, the .NETCompute node introduces a feature known as hot swap 
deploys.This feature ensures that the WebSphere Message Broker runtime will monitor a 
.NET assembly that the hot swap deploy or node or broker uses for changes. If the 
WebSphere Message Broker runtime detects any changes to this dll file, it automatically 
reloads the node and changes will take effect. 

To test the hot swap deploy feature: 

1 . In Visual Studio, modify CreateNode.es so that the length variable has 1 added to it. You 
must modify the line shown in Example 3-2. 

Example 3-2 Modifying the code in CreateNode.es 

int length = inputRoot["BLOB"] . LastChi 1 d.GetByteArrayO .Length + 1 ; 


2. Save CreateNode.es, and rebuild the project. 

In the Windows Event Viewer for applications, you will see a BIP 7451 message indicating 
that the broker reloaded an assembly, as shown in Figure 3-14. 



Figure 3-14 A hot swap deploy 

3. If you resend the same input message, you can see that the output message contains a 
count of seven, as shown in Figure 3-15 on page 63. 
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Figure 3-15 The new input message has a count of 7 


3.3 Using the Visual Studio debugger 

Another advantage of the integration between Visual Studio and WebSphere Message Broker 
is that developers of .NETCompute nodes can use the first class debugging capabilities of 
Visual Studio.This integration saves developers time and gives tools to diagnose problems in 
their .NET code. 

To debug the example: 

1 . To set a breakpoint in the CreateNode.es file, click in the gray margin in the code editor 
window, as shown in Figure 3-16. A second click will delete the breakpoint. 
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int length = inputRoot ["BLOB"] . lastChild.GetByteArrayQ .Length + 1 ; 

f^reateNode.cs, line 38 character 17 CCountCharsNode.CreateNode.Evaluate*JNBMessage Assembly inputAssembly} 1 , line 20) | 


Figure 3-16 Setting a breakpoint 

2. Attach the Visual Studio debugger to the running execution groups by selecting Debug -» 
Attach to Process. 

3. In the Attach To Process dialog, select the DataFlowEngine process, and click Attach. 
Select the Show processes from all users and the Show processes in all sessions to 
see the DataFlowEngine option. There is a DataFlowEngine for each broker that is 
running. An example of attaching to a process is shown in Figure 3-17 on page 64. 
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Figure 3-17 Attaching the DataFlowEngine to a process 


Attach 


Cancel 


Execution will now halt whenever the breakpoint is passed. To trigger the debugger, send a 
third message to the COUNTJN queue. The debugger will then halt, as shown in Figure 3-18 
on page 65. 


64 


Using WebSphere Message Broker V8 in Mid-Market Environments 




00 CountCharsNode (Debugging) Microsoft Visual Studio 

File Edit View Project Build Debug Team Data Tools Test Window Help 

1 . j3 - _lJ w \3 iid ^ U --j S& . J - p 

, - I IF =F -= *2: | — I > J ^ t 

: Process: [0x2D44] DataFlowEngine.exe - Thread: | [0x9CC] <No Name> 


I 


QliisUa A 

[33 Solution 'CountCharsNode' (1 project) 
0- 09 CountCharsNode 
0 l^| Properties 
® jai References 
<U CreateNode.es 



w x Team Explorer 


NBMessageAssembly outAssembly = new NBMessageAssembly(inputAssembly, outputMessage) ; 
NBElement inputRoot = inputMessage.RootElement; 

NBElement outputRoot = outputMessage. RootElement; 

// Optionally copy message headers, remove if not needed 
CopyMessageHeaders (inputRoot, outputRoot); 

#region UserCode 

// Add user code in this region to create a new output message 

|int length = inputRoot["BLOB"] . LastChild.GetByteArrayQ . Length + 1 ;| 


NBElement xmlnscOutputElement = 

outputRoot. CreateLastChildUsingNewParserC'XMLNSC"); 
NBElement xmlRoot = xmlnscOutputElement. CreateFirstChild(”Output"); 
xmlRoot. CreateLastChild( “Count" ) .SetValue( length); 


#endregion UserCode 


// Change the following if not propagating message to the 'Out' terminal 
outTerminal . Propagate (outAssembly) ; 


|CopyMessageHeaders| 


Name 

Value 

Type 

S inputRoot 

(Root) 

IBM.Brol 

SI ^ inputRootTBLOBTLastChild 

(BLOB) 

IBM.Brol 

length 

0x00000000 

int 

S «/ outputRoot 

(Root) 

IBM.Brol 

S «/ this 

(CountCharsNode. CreateNode 

CountCI 



Name 

Langi 

J 

CountCharsNode.DLL!CountCharsNode.CreateNode.Evaluate(IBM.Broker.Plu 

C# 


IBM.Broker.Support.dll!<Module>.IBM.Broker.lmbClrAppDomainManager<8>.in 



IBM.Broker.Support.dll!<Module>.IBM.Broker.DomainTransitionArgs4<bool,IBN 



IBM.Broker.Support.dll!<Module>.IBM.Broker.DomainTransitionArgs4<bool,IBN 



[Appdomain Transition] 



[Native to Managed Transition] 



[Managed to Native Transition] 



IBM.Broker.Support.dll!<Module>.IBM.Broker.wmb_call_in_appdomain<bool,cl 



IBM.Broker.Support.dll!<Module>.IBM.Broker.lmbClrAppDomainManager<8>.in 



Wl Locals ffi Watch 1 


Figure 3-18 Execution halts at the breakpoint 
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After execution stops, the .NET developer can examine the content of variables, examine the 
stack backtrace, and single step through execution exactly as they would with a command line 
.NET application. 

You can stop the debug, by selecting Debug -> Stop Debugging. 
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Scenario: Bridging WebSphere 
MQ and Microsoft Message 
Queuing 


The scenario in this chapter demonstrates a number of best practice development techniques 
using WebSphere Message Broker and .NET applications. We use the relatively simple case 
of constructing a messaging bridge between WebSphere MQ and Microsoft Message 
Queuing (MSMQ). The scenario features a customer who has a sales application that 
produces and receives data as messages on MSMQ queues and the customer must move 
these messages to an Enterprise Service Bus (ESB) that uses WebSphere MQ. 

This scenario features the following techniques: 

► Receiving messages from MSMQ into a message flow and sending them to WebSphere 
MQ 

► Receiving messages from WebSphere MQ and sending them to MSMQ 

► Handling transactions against MSMQ objects 

► Using logging from .NET code in a message flow 

► Managing exceptions in .NET code 


Additional materials: The WebSphere Message Broker project interchange file and the 
.NET class code for this scenario can be downloaded from the IBM Redbooks publication 
web site. See Appendix A, “Additional material” on page 485 for more information. 


© Copyright IBM Corp. 2012. All rights reserved. 
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4.1 Scenario overview 


This scenario creates a message flow to bridge between WebSphere MQ and MSMQ, as 
shown in Figure 4-1. 


MSMQ 

Queue 


lit- 


Read 


f\l 

.NET 


Read from 
MSMQ Queue 


Write 


MSMQ 

Queue 


/V 

b n 

.piK, — 

.NET 

r 

■IsP - 


Message Broker 
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Figure 4- 1 WebSphere MQ to MSMQ bridge 


A broker flow uses a TimeoutNotification node to initiate message processing on a repeating 
basis. This process drives a .NETCompute node that reads individual messages from a 
MSMQ queue until the queue is empty. Each message is read in a transaction and 
propagated to an MQOutput node. When the MQOutput node completes, the .NETCompute 
will complete the transaction and read the next message from the queue. 

A second flow uses an MQInput node to read individual messages from MQ. These 
messages are then transformed and written into a MSMQ queue in a transaction. This MSMQ 
transaction will complete successfully when the MQInput node completes its transaction. The 
MSMQ will be named by a user-defined property, and the flow will access this and use it. 

The .NET code in these nodes is written to expose WebSphere Message Broker development 
best practices in terms of .NET persistent object management, appropriate exception 
catching and handling mechanisms, and any needed logging. 

This scenario uses the following software: 

► MSMQ is enabled on the same system where WebSphere Message Broker is installed. To 
enable MSMQ on Windows 2008 Server: 

a. Select Start Server Manager. 

b. In the Server Manager window, click Features, and click Add Features. 

c. Expand Message Queuing Message Queuing Services. 

d. Select Message Queuing Server. 

e. Click Next, and then click Install. 

f. After the feature is installed, click Close. 
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► Microsoft Visual Studio 2010 is installed. 

► WebSphere MQ 7.0.1 .3 is installed. 

► WebSphere Message Broker V8 is installed: 

- A broker and its queue manager was created. 

- Queues named ESB.IN and ESB.OUT have been defined on the broker’s queue 
manager. 


4.2 Receiving messages from MSMQ 

In the first part of this scenario, you will: 

► Construct a message flow that reads messages from a MSMQ queue and forward them to 
an MQ queue. 

► Construct a simple desktop application to read and write MSMQ messages to provide for 
some basic testing utilities and to get comfortable with the .NET coding mechanisms for 
MSMQ. 

4.2.1 Constructing a simple utility to read and write MSMQ messages 

This section tells you how to construct a Microsoft Forms application to read and write simple 
MSMQ messages. You can use this application to do some basic testing of your message 
flows to ensure that they work. 

Creating a new Visual Studio project 

Open Visual Studio and use the following procedure to create a new project. 

1 . Select File -» New ->• Project, as shown in Figure 4-2 on page 70. 
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Figure 4-2 Create a new Windows Forms Application 
Perform the following steps: 

a. In the Recent Templates column, select Visual C# and in the list of templates, select 

Windows Forms Application. 

b. In the Name field, enter MSMQUti 1 . 

c. In the Location field, enter c:\projects\VIStudio. 

Note that the location of the project is moved from the default directory for Visual 
Studio projects to provide a more convenient location for keeping the .NET code and 
the WebSphere Message Broker code together. The WebSphere Message Broker 
code will be kept in a workspace under c:/projects as well. 

In the Solution field, MSMQUtil is automatically filled in for you. 

d. Click OK. The new form displays, as shown in Figure 4-3 on page 71 . 
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Figure 4-3 New Forms Application after creation 


Constructing the form 

The next step is to construct the form: 

1 . Rename the form. In the Solution Explorer, right-click Forml.cs and select Rename. 
Enter MSMQUti 1 . cs as the new name. 

2. At the prompt shown in Figure 4-4, click Yes. 



Figure 4-4 Rename prompt 

3. Use the Visual Studio Designer to create this form. You can access the Designer by 
selecting the MSMQUtil.es file in the Solution Explorer and clicking the View Designer 
button, as shown in Figure 4-5. 



Figure 4-5 Select View Designer 
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4. In the Toolbox palette on the left side of the window, expand Common Controls, and use 
your cursor to drag-and-drop the necessary control objects into the appropriate locations 
to create the form shown in Figure 4-6. You can also use your cursor to size the form and 
the control objects in the form. 

If you do not see the Toolbox, select View ->• Toolbox. 



Figure 4-6 The basic MSMQUtil form 
To create the form: 

a. Add a Label and a Textbox at the top of the form to allow the user to input the name of 
the MSMQ queue. Enter Queue Name as the text for both the label and the textbox. 

The visible attributes of the control objects are set in the properties pane of Visual 
Studio, including the names of the objects. If the properties pane is not open and 
visible, select one of the control objects, and right-click to choose Properties. 

b. Add three buttons to the form. 

c. Use the Properties view to add the text shown in Figure 4-6 to the Text property for 
each button. 

d. Use the Properties view to name the buttons createQueue, readQueue, and writeQueue 
respectively. The name is set in the (Name) property in the Design section of the 
properties. 

e. Add another Label called Data below the row of buttons and a RichTextBox to hold the 
contents of the message. 

Save the design and close the Properties view. 

5. Add a reference in the project to the System. Messaging component. In the Solution 
Explorer, right-click References and select Add Reference. 

6. In the Add Reference window, shown in Figure 4-7 on page 73, select the .NET tab and 
then select the System. Messaging component. Click OK. This reference allows your 
code to find the necessary runtime libraries when it executes. It also allows Visual Studio 
to validate the code you’re writing against those runtime libraries. 
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Figure 4-7 Add References 
7. Save the design by pressing Ctrl+S. 

Writing the code 

To construct the three methods that will be called by the different buttons: 

1 . Double-click the form design to open the MSMQUti 1 . cs code. 

2. Add the System. 10 and System. Messaging namespaces to the code. Add the statements 
shown in Example 4-1 to the list of using statements at the top of the file. 

Example 4- 1 Add the using statement for System.Messaging namespace 

using System.Messaging; 
using System. 10; 


3. Declare some class variables (shown in bold in Example 4-2). Create a variable to hold 
the contents of the message we are going to write, a variable to hold the Message Queue 
object, and a variable to hold the name of the queue we are going to open. 

Example 4-2 Class variables for MSMQUtil 

namespace MSMQUtil 

{ 

public partial class MSMQUtil : Form 

{ 

private String myText; 
private MessageQueue myQ; 
private String myName; 

publ i c MSMQUti 1 () 


4. Add the code for the methods that will get performed when the user clicks each of the 
three buttons. The createQueue_Click method will open or create the queue. Add the 
code shown in Example 4-3 on page 74. 
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To create the stub of this method and ensure that it is invoked when the button is pushed, 
double-click each of the three buttons in the Designer view. It will create and associate a 
new method with each button. 

Example 4-3 Create Queue method for MSMQUtil 

private void createQueue_Cl ick(object sender, EventArgs e) 

{ 

myName = textBoxl.Text; 

if ( ! MessageQueue . Exi sts (myName) ) 

{ 

myQ = MessageQueue. Create (myName) ; 

} 

el se 

{ 

myQ = new MessageQueue(myName) ; 

} 


5. The readQueue_Cl i ck method opens the queue, if it is not already open (and create it if it is 
not created), and then extracts the first message and puts the contents of the message 
into the text box. It then displays a user message to indicate that the reading was 
successful. Add the code shown in Example 4-4 to the stub method created by 
double-clicking this button. 

Example 4-4 Read a message from the queue and populate the text box 

private void readQueue_Cl i ck(object sender, EventArgs e) 

{ 

myName = textBoxl.Text; 
i f ( IMessageQueue. Exi sts (myName) ) 

{ 

createQueue_Cl i ck(sender, e); 

} 

el se 
{ 

myQ = new MessageQueue(myName) ; 

} 

System. Messaging. Message myMsg; 
myMsg = myQ.Receive() ; 
if (myMsg != null) 

{ 

Byte[] myBytes = new Byte[(int)myMsg.BodyStream. Length] ; 

StreamReader myTR = new StreamReader(myMsg.BodyStream) ; 
myText = myTR.ReadToEnd() ; 
richTextBoxl.Text = myText; 

MessageBox.Show(this, "Read the message from queue 11 + myName + 
"successfully", "MSMQ UTIL", 

MessageBoxButtons.OKCancel ) ; 

} 


The code uses a StreamReader to get the contents of the message body as a 
single-String field. 
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6. The wri teQueue_Cl i ck method will also create and open the queue. It then puts whatever 
text is in the text box into a local string variable and writes that into a new message on the 
queue. It then displays a user message indicating that the message was successfully put 
on the queue. Add the code shown in Example 4-5 to the stub method generated by 
double-clicking the button. 

Example 4-5 Write the contents of the text box as an XML Message to the queue 

private void wri teQueue_Cl ick (object sender, EventArgs e) 

{ 

myName = textBoxl.Text; 
try 
{ 

i f ( IMessageQueue. Exi sts (myName) ) 

{ 

createQueue_Click(sender, e); 

} 

el se 

{ 

myQ = new MessageQueue(myName) ; 

} 

myText = richTextBoxl.Text; 

System. Messaging. Message myMsg = new System. Messaging. MessageQ ; 
StreamWriter mySW = new StreamWri ter (myMsg. BodyStream) ; 
mySW.Write(myText) ; 
mySW.Flush() ; 
if (myText != null) 

{ 

myQ. Send (myMsg) ; 

} 

MessageBox.Show(this, "Wrote the message to queue " + myName + 
"successfully", "MSMQ UTIL", 

MessageBoxButtons.OKCancel ) ; 
richTextBoxl.Text = 

} 

catch (Exception) 

{ 

throw; 

} 


This code uses a StreamWriter to insert the contents of the String into the message body, 
and then flushes the buffer to ensure that the string is written. This method produces a 
plain text message on the queue. 

7. Close the MSMQUti 1 . cs file and the form design. 

Testing the program 

To execute some basic testing to ensure that the code works: 

1 . Launch the program by clicking Start Debugging in Visual Studio, shown in Figure 4-8. 



Figure 4-8 Start Debugging button 


Chapter 4. Scenario: Bridging WebSphere MQ and Microsoft Message Queuing 75 



2. In the Queue Name box, enter the value Apri vate$\test. Click the Create Queue 
button.The application does not notify you that this method succeeds, but you can check it 
using the Server Manager Console (see step 4). 

3. Enter some text into the Data box, such as the text shown in Figure 4-9. Click the Write 
Queue button. 



Figure 4-9 Testing the Write Queue button 

The success message box is displayed, as shown in Figure 4-10. 



Figure 4-10 Test message sent successfully 

4. After the dialog box indicating that the message was written successfully is displayed, 
open the Windows Server Manager console, and navigate to your new private queue in 
the MSMQ section, as shown in Figure 4-1 1 on page 77. 


76 


Using WebSphere Message Broker V8 in Mid-Market Environments 






Figure 4-11 MSMQ Server Manager view 

5. Right-click the message, and select Properties in the Body tab to view the message you 
sent in plain text, as shown in Figure 4-12. 
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Figure 4- 12 MSMQ message properties showing the Body 
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4.2.2 Constructing and testing a basic message flow 


The next step is construct a message flow that will use .NET code to read messages that are 
delivered to an MSMQ queue. WebSphere Message Broker V8 does not currently provide a 
means for .NET code to initiate a message flow. There is not a .NETInput node, and you 
cannot create a custom Input plug-in using .NET code. However, the Standard and Advanced 
Editions of WebSphere Message Broker V8 provides the TimeoutNotification node. This 
node propagates an empty message to its out terminal at a configurable interval. 

Before starting this procedure, make sure that WebSphere Message Broker V8 is running. 

Constructing the message flow 

To create the message flow: 

1 . Open the WebSphere Message Broker Toolkit. 

2. Create a new application called sal esConnector . 

3. Create a new message flow called readSal es. (See 2.7, “Getting started” on page 33) 

4. Construct the message flow using the following steps: 

a. Drag-and-drop the TimeoutNotification node in the Timer folder on the Palette to the 
Canvas. 

b. Drag-and-drop the .NETCompute node in the Transformation folder on the Palette to 
the Canvas. 

c. Drag-and-drop the MQOutput node from the WebSphere MQ folder on the Palette to 
the Canvas. 

d. Wire the out terminal of the TimeoutNotification node to the in terminal of the 
.NETCompute node. 

e. Wire the out terminal of the .NETCompute node to the in terminal of the MQOutput 
node. 

Your flow now looks like the flow in Figure 4-13. 
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Figure 4-13 Message Flow to read MSMQ 


The red boxes and yellow warning flags are present because the nodes have not yet been 
configured. 

Configuring the message flow 

To configure the relevant properties on the message flow, including adding the necessary 
user-defined properties: 

1 . Select the TimeoutNotification node on the canvas and, in the Properties view Basic tab, 
set the Unique identifier to the value readSal es . 

2. Promote the Timeout interval (sec) property to the message flow. 
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a. Right-click the TimeoutNotification node, and select Promote Property. This process 
allows the property to be set on the flow along with the user-defined properties and 
allows the timeout interval to be altered at runtime without redeploying the flow. 

b. In the Available node properties column, expand the Basic section, select Timeout 
Interval (sec), and click Promote. The Target Selection screen displays. 

c. Click OK to put the property in the readSales group. 

The results are shown in Figure 4-14. 



Figure 4-14 Promoted properties 

d. Click OK again to close the window. Figure 4-15 shows the resulting properties. 
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Figure 4-15 Timeout Node properties 


3. Select the MQ Output node on the Canvas and, in the Basic tab of the Properties view, 
specify a Queue name of ESB. IN, as shown in Figure 4-16 on page 80. 
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Figure 4-16 MQOutput properties 


4. Create two user-defined properties, one to hold the name of the MSMQ queue and one to 
hold the number of seconds to wait for a new message. Both properties are String type 
because non-String properties are not currently supported by the runtime. 

To create the properties: 

a. Select User Defined Properties at the bottom of the Message Flow Editor. 

b. Select Basic, and click the Add Property button, as indicated by the arrow in 
Figure 4-1 7. Enter Sal esQueueName and select String as the type to define the name of 
the queue. 

c. Click the Add Property button again. Enter Sal esWai t Interval , and select String as 
the type to define the wait interval. 

Figure 4-17 shows the two new user properties. 
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Figure 4-17 User defined properties 


5. Return to the Graph view. 

Creating the .NET code 

The next step is to create the Visual Studio project and the .NET code associated with the 
.NETCompute node. The Message Broker Toolkit makes it easy to do this. 

To create the Visual Studio project and the .NET code associated with the .NETCompute 
node: 

1 . Double-click the .NETCompute node in the message flow to launch Visual Studio. 

2. Select File -» New -» Project to create a new project. 
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Follow these steps to configure the project: 

a. In the Recent Templates column, select Visual C# -» Message Broker. In the list of 
templates, select Project To Create A Message Broker message. 

b. In the Name field, enter ReadQueue. 

c. In the Location field, enter the location to store the project, for example, 
c:\projects\VIStudio. 

d. In the Solution field, ReadQueue is automatically populated. 

e. Click OK. 

3. An editor with the new code template is displayed. Add a reference in the project to the 
System. Messaging component. 

a. In the Solution Explorer, right-click References, and select Add Reference. 

b. In the Add Reference window (see Figure 4-7 on page 73), select the .NET tab, and 
select the System. Messaging component. 

c. Click OK. 

4. Click the CreateNode.es tab to display the code, add the System. Messaging namespace, 
and add the System. Globalization namespace to the code by adding the following syntax. 
Use statements from the list at the top of the file: 

using System. Messagi ng; 
using System. Globalization; 

5. Save your changes by pressing Ctrl-S. 

Writing the code 

To create the code for the .NETCompute node: 

1 . The class that is created has a default name of CreateNode. Even though it is put into a 
namespace of ReadQueue after your Solution name, we change the name of the class to 
ReadQueueNode instead: 

a. In the Solution Explorer, right-click CreateNode.es, and select Rename. 

b. Rename the class to ReadQueueNode.es. 

c. A Visual Studio message is displayed that asks if you want to also rename all 
references to this element. Click Yes. 

2. Add the code, shown in bold in Example 4-6, to the ReadQueueNode class in 
ReadQueueNode.es. to create the following class variables: 

- The salesQueue variable is the Microsoft Messaging Queue object representing the 
queue. 

- The salesQName holds the actual name of the queue. 

- The salesWaitlnterval is the time in seconds that the flow waits for a new message to 
arrive before terminating the flow. 

Example 4-6 ReadQueueNode class variable 

public class ReadQueueNode : NBComputeNode 

( 

MessageQueue salesQueue; 

String salesQName; 
int salesWaitlnterval; 
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d. Create a constructor for the node. Add the code in Example 4-7 directly below the last 
variable from Example 4-6 on page 81 . 

Tip: If you start typing publ i c overri de, the code completion in Visual Studio displays a 
pop-up of the methods of the class to override. Select Onlnitialize to obtain the skeleton of 
the method. 


public override 

1 

/// <sumiTiary> 

/// Evaluate Met 
/// </suuiiTiary> 
/// <param name= 

Equals[object obj) 
^ GetHashCodeQ 
DnDeleteQ 
^ QnlnitializeO 


Example 4-7 Onlnitialize method of the node class 

public override void Onlnitial ize() 

{ 

base.0nlnitialize(); 

salesQName = GetUserDefinedPropertyAsString("SalesQueueName") ; 

String mylnt = GetUserDefinedPropertyAsString("SalesWaitInterval ") ; 
try 
{ 

salesWaitlnterval = Convert. ToInt32(myInt, Cul turelnfo. InvariantCul ture) ; 

} 

catch (System. FormatExcepti on ) 

{ 

salesWaitlnterval = 30; 

//Default value of 30, if the User Defined Property is not a valid integer. 

} 

catch (System. OverflowException ) 

{ 

salesWaitlnterval = 30; 

//Default value of 30, if the User Defined Property is not a valid integer. 

} 

i f ( IMessageQueue. Exi sts (sal esQName) ) 

{ 

salesQueue = MessageQueue.Create(salesQName) ; 

sal esQueue. Set Permissions ("Users", MessageQueueAccessRights.Ful 1 Control ) ; 

} 

el se 

{ 

salesQueue = new MessageQueue (sal esQName) ; 

} 


You now have code that reads the user-defined properties that you created on the 
message flow. This code uses the name property to create and open the MSMQ queue to 
be used during the main flow execution. 

We also use a basic try/catch block to ensure that the SalesWaitlnterval user-defined 
property on the flow is convertible to an integer value. If it is not convertible to an integer 
value, we ignore the reason and set the timeout to a fixed 30-second interval. WebSphere 
Message Broker does not currently support user-defined properties that are not String 
values; therefore, we cannot enforce this value to be an integer at deployment time, so we 
use the try/catch logic to enforce it during runtime. 


82 


Using WebSphere Message Broker V8 in Mid-Market Environments 



If the broker code created the queue, it also explicitly grants all permissions to all 
members of the Windows group “Users”. This process ensures that our desktop 
application can interact with the same queue. Remember that your broker is not going to 
run as the same user that you are logged in as, and otherwise does not have sufficient 
access. 

You can also manually create the MSMQ queue before the message flow tries to access it. 
If you do this, you must ensure that you set the needed permissions. The desktop 
application that we wrote in 4.2.1 , “Constructing a simple utility to read and write MSMQ 
messages” on page 69 does not set any permissions on the queue, so it is automatically 
private to the user running the application. You can modify the application to add the same 
code to set all permissions, or you can use the Microsoft Server Manager console to 
create the queue and set whatever permissions are appropriate. 

For the purposes of this scenario, the broker creates the queue and thus all users have full 
control. 

3. Having created the constructor, you must create the destructor to make sure that the 
queue is closed when we are finished. Add the code shown in Example 4-8 directly below 
the Onlnitialize() method. 

Example 4-8 OnDelete method of the node class 

public override void OnDelete () 

{ 

salesQueue.Close() ; 
base.OnDelete() ; 

} 


4. The next step is to construct the method that is invoked when the TimeoutNotification 
node passes control to the in terminal of the .NETCompute node. This is the Evaluate 
method. A skeleton of this method is already created for you that handles the main parts of 
creating a new message and sending it to the out terminal. 

We must modify this method so that it repeatedly reads messages from the MSMQ queue, 
puts the data from each message into the logical message tree, and forwards this to the 
out terminal for writing to an MQ queue. 

To accomplish this, perform the following steps: 

a. Create the skeleton of the output message. This is created once for each time the 
.NETCompute node is invoked, and then reused for each MSMQ message read. 

b. Create a loop that gets each message from the queue until the queue indicates that it 
is currently empty. 

c. Read a message from the queue, and specify a timeout using the value of the 
user-defined property that was read in the constructor method. If the message is not 
returned until the timeout expires, an lOException is thrown. If the lOException is not 
thrown, read the bytes from the BodyStream of the MSMQ message object, insert 
them into the NBEIement in the logical message tree, and then propagate out of the 
node. 

Use the code in Example 4-9. Add this code to the user region in ReadQueueNode.es. 

Example 4-9 UserCode region of Evaluate() method 
Iregion UserCode 

// Add user code in this region to create a new output message 
// Create the output message structure for a BLOB message. 

output Root .CreateLastChi 1 dUsi ngNewParser (NBParsers .BLOB. ParserName) ; 
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NBElement blob = outputRoot [NBParsers . BLOB. ParserName] .CreateLastChi 1 d (nul 1 , 
"BLOB"); 

// Create the object to hold each MSMQ message. 

System. Messaging. Message myMsg = new MessageQ; 

// read the queue until it's empty, 
while (myMsg != null) 

{ 

try 

{ 

//Read the message from the queue. 

myMsg = sal esQueue. Recei ve(new TimeSpan(0, 0,0, salesWaitlnterval)) ; 

//Construct and populate a Byte array holding the data in the msg body 

Byte[] myBytes = new Byte[(int)myMsg.BodyStream. Length] ; 

myMsg. BodyStream. Read (myBytes, 0, (int)myMsg.BodyStream. Length) ; 

//Add data to the NBElement that represents the body of the blob message 
bl ob.SetVal ue(myBytes) ; 

//Send the message to the next node in the message flow. 
outTermi nal . Propagate(outAssembly) ; 

} 

catch (System. Messaging. MessageQueueExcepti on e) 

{ 

if (e.MessageQueueErrorCode == MessageQueueErrorCode. IOTimeout) 
myMsg = null; 
el se 
throw; 

} 

} 

lendregion UserCode 


5. Most of the code that is outside of the marked user region can be left alone. The line of 
code immediately below the UserCode region that calls propagate (in bold in 
Example 4-10) is redundant, so comment it out. 

Example 4-10 
#endregion UserCode 

// Change the following if not propagating message to the 'Out' terminal 

//outTermi nal .Propagate (outAssembly) ; 


6. Save and close the ReadQueueNode.es file. 

7. Select Build Build Solution to test the code. 

Select the Output tab at the bottom of the screen to view the messages from the build and 
to ensure that the build was successful. 

Updating the .NETCompute node 

Now that you have the code, you must update the message flow to use it: 

1 . In the Message Broker Toolkit, click the .NETCompute node. 
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2. In the Properties view, select the Basic tab: 

a. In the Assembly name field, browse to the following location, and select the 
ReadQueue.dll file: 

C:\projects\VIStudio\ReadQueue\ReadQueue\bi n\Debug\ReadQueue.dl 1 

b. Click Open. 

c. Enter the ReadQueueNode as the class name. 

3. Select the Advanced tab in the Properties view, and enter ReadSal es as the AppDomain 
name. This process ensures that this .NETCompute node’s DLL is loaded in a unique 
.NET application domain and does not interfere with other flows in the same broker 
application. 

4. Save the message flow. 

Testing the message flow 

To test the message flow: 

1 . Create a BAR file to deploy your message flow application. In the Message Broker Toolkit, 
right-click your application, and chose New -> BAR File. The window shown in 

Figure 4-18 is displayed. 

2. Enter a name for the BAR file and either put the file in the normal BAR Files container or a 
project of your choosing. 



Figure 4-18 Create a BAR file for deployment 

3. Click Finish. 

4. Add your application to the BAR file by selecting the check boxes on the Prepare tab, as 
shown in Figure 4-19 on page 86. 
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IU1 read5ales.msgflow ■ *sales.bar 

Prepare 

Select deployable resources to include ii 
Deployable Resources 

Select an application to package all its contained resour 
applications. 

© Applications O Message flows, libraries and other 
Text filter: (type filter text 



Prepare Manage User Log Service Log 


Figure 4-19 Add the application to the BAR file 

5. Click the Build and Save button to build the BAR file, and then click OK. 

6. Select the Manage tab. Expand your application, and select the readSales compiled 
message flow. 

Name | Type 

□ [A I salesConnector Application 

- HH1 readSales .cmf Compiled message flow 


□ readSale: 


| ,{Y t .NETCompute | 

Figure 4-20 Select the message flow to edit the deployable properties 

7. In the Properties view, set the SalesQueueName to a valid UNC path that names the 
correct queue. For the purposes of this scenario, use .\private$\SALESOUT to indicate a 
queue on the local machine in the private area named salesout. 

8. Set the SalesWaitlnterval and the TimeoutNotification node timeout intervals to 30 
seconds, as shown in Figure 4-21. 


Properties 

U Problems IS Deployment Log 

readSales 


1 

Configure 

(T) Configure properties of selected built resource. 


5alesQueueName j .\private|\5ALE50UT| 


SalesWaitlnterval | n 


Timeout interval (sect | jU 

Figure 4-21 

Edit the deployable properties 
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9. Save the BAR file, and deploy it by dragging it from the Broker Development view onto the 
execution group in your local broker. 

If the BAR file does not deploy, you receive a message with the option to view the details 
of the error. The information gives you an idea of the problem. If the .NETCompute node is 
called out as the problem, review the settings in “Updating the .NETCompute node” on 
page 84. If so, update the settings and then rebuild and deploy the bar file. 

Your queue was created in the Server Manager view, as indicated by the red arrow in 
Figure 4-22. (You might need to refresh the view). 



Figure 4-22 New Queue visible in Server Manager 

Note that MSMQ forced the name of the queue into lowercase. 

10. You can now use the test application we built in 4.2.1 , “Constructing a simple utility to read 
and write MSMQ messages” on page 69 to write messages to this queue. 

Enter the name . \pri vate$\SALESOUT into the queue name box in the MSMQUtil, and then 
enter the text Hel 1 o Sales Message Flow into the data box, and click the Write Queue 
button, as shown in Figure 4-23. 



Figure 4-23 Write data to the queue 

1 1 .Use the WebSphere MQ Explorer to view the message on the output queue. 
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Expand the queue manager, and select Queues. Right-click the ESB.IN queue in the 
Content pane, choose Browse Messages. Select the first message in the viewer, and 
choose Properties. Figure 4-24 is the message that is displayed. 



Figure 4-24 Verify the message arrived at WebSphere MQ 
Again, we see that the message is plain text. 


4.3 Mapping headers between MSMQ and WebSphere MQ 

WebSphere MQ Messages have a number of important headers on them and a set of 
associated metadata that forms a logical context around the data in the message. When 
moving messages from a WebSphere MQ messaging network onto an MSMQ network or the 
other way around, it is important to understand the context and to carry the relevant parts of it 
through. 

Table 4-1 shows the properties that are available on an MSMQ message that can be directly 
mapped to properties on a WebSphere MQ message. 


Table 4- 1 MQ message mapping properties 


MSMQ 

WebSphere MQ 

Id 

MessagelD 

CorrelationID 

CorrelationID 

Priority 

Priority 
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MSMQ 

WebSphere MQ 

ResponseQueue 

ReplyToQueue 

SentTime 

PutTime and PutDate 

Recoverable 

Persistence 


Most of the remaining properties that exist on a given Microsoft Messaging Queue message 
can be stored without change into WebSphere MQ message properties. 


4.4 Adding logging to your code 

There are several kinds of code-level instrumentation that can be used with a .NET solution in 
WebSphere Message Broker. You want to ensure that you can provide adequate information 
about the normal operation of your flow. You also want to ensure that you can debug your 
code effectively in a production environment without requiring significant updates. 

The .NET V4 framework provides the System. Diagnostics namespace and the 

Systems.Diagnostics.Trace, System. Diagnostics.TraceSource, and 

System. Diagnostics. Debug classes to allow you to easily instrument your own code. 

You can continue to use these methods within your .NET code running inside a WebSphere 
Message Broker .NETCompute node. However, be aware of a couple of things: 

► WebSphere Message Broker has a separate standard output console and standard error 
console for each execution group. In Windows, there is a single file for each execution 
group that contains both the standard output console and the standard error console. This 
file is kept in the broker’s working storage area. The file is named console.txt and is in 
the following location: 

C : \ProgramData\IBM\MQSI\components\<Bro/cer Name>\<ExecutionGroup Unique ID>\ 

<Broker Name> is the name of the Broker, and <ExecutionGroup Unique ID> is a string that 
contains the unique identifier of each ExecutionGroup. See the topic for Directory 
Structures After Installation in the WebSphere Message Broker Information Center for 
further details: 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8rOmO/index.jsp7%2Fconi.ibm.et 
ool s .mft.doc%2Fbh44510_.htm 

► If you use the DefauItTraceListener and you enable it to write to Console.Out or you 
otherwise use standard print statements to write to Console.Out or Console.Error, this is 
the file your statements will end up in. This can lead to a disk full error or otherwise cause 
additional noise in this log file that will make it harder to debug other problems. 


Important: Avoid using standard write statements and TraceListeners and other loggers 
that unilaterally output to the standard Console.Out and Console.Error. 


The WebSphere Message Broker .NET APIs also provide the NBLog class to allow your 
.NETCompute node to output data into the standard areas that WebSphere Message Broker 
writes out information. WebSphere Message Broker flows typically output logging and tracing 
information into two locations: The Windows Event log (or other system log on non-windows 
systems) and an internal set of user trace files that can be read and processed using the 
broker commands. 
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The NBLog class provides methods to allow your .NETCompute node to access both of these 
functions. You can write a custom TraceListener object to enable the System. Diagnostics 
frameworks to output to the WebSphere Message Broker standard locations. Example 4-1 1 
shows a simple example. 

Example 4-11 TraceListener that knows about broker trace facilities 

using System. Diagnostics; 
using System. Text; 
using IBM. Broker. Plugin; 

public class NBLogListener : TraceListener 

{ 

//2951 is the default value, it is the number of the lowest message 
//in the block of reserved numbers for user messages. 

public int MessageNumber = 2951; 

System. Diagnostics. Bool eanSwitch writeToEventLog = new 

System. Di agnosti cs . Bool eanSwi tch (“Wri teToEvent Log”, 

’’Enables output to the event log”); 

public override void Write(string message) 

{ 

if (NBLog. UserTraceActive) 

{ 

NBLog. LogllserTrace (MessageNumber, message) ; 

} 

if (writeToEventLog. Enabled) 

{ 

NBLog. LogEvent (MessageNumber, NBSeverity. Information, message); 

} 

} 

public override void Wri teLine (string message) 

{ 

if (NBLog. UserTraceActive) 

{ 

NBLog. LogUserTrace (MessageNumber, message) ; 

} 

if (writeToEventLog. Enabled) 

{ 

NBLog. LogEvent (MessageNumber, NBSeverity. Information, message); 

} 

} 

} 


This listener creates a class variable to hold the message number for the error message 
being reported under the WebSphere Message Broker catalog. It initializes this to the default 
message number for the first error in the range of numbers set aside by the broker for 
user-created error messages. 

It creates a second class variable that holds a Boolean Trace Switch object. If this trace switch 
is true, the broker outputs the provided trace message into the Event Viewer Application Log. 
This TraceListener also checks the NBLog. UserTraceActive field to determine if the broker 
user tracing is enabled. If user tracing is enabled, this class also outputs the message to the 
user trace. 
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To use this TraceListener in your .NETCompute node, you can write code similar to the code 
in Example 4-12. 

Example 4-12 Using a new TraceListener 

// Create and add a new trace listener. 

NBLogListener brokerLi stener; 
brokerListener = new NBLogLi stener () ; 

Trace. Listeners .RemoveAt (0) ; // Remove the default listener 
Trace. Li steners .Add(brokerLi stener) ; 

//Log a message 

System. Di agnosti cs. Debug. WriteLi ne( ' Hel 1 o. Broker Log!'); 


Any of your other code that is already instrumented with the System. Diagnostics Tracing 
frameworks also outputs data to the Event Log or the user trace as configured. 

You can control the state of the wri teToEventLog Trace Switch by using an application 
configuration file. This file is deployed to the same location as your .NETCompute node’s 
DLL. Visual Studio allows you to create a configuration file for your application and provides 
context-sensitive help for editing it. 

Follow these steps: 

1 . Right-click our project folder in the Solution Explorer. Select Add -» New Item. 

2. Select Application Configuration File from the Visual C# items in the Installed 
Templates, as shown in Figure 4-25. 



Figure 4-25 Creating a new XML file 
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3. Click Add to creates a new XML file named App.config, as shown in Figure 4-26. 



Figure 4-26 App.config file 

Example 4-1 3 shows the file contents. 

Example 4-13 Initial Application Configuration file 

<?xml version="1.0" encodi ng="utf-8" ?> 
<configuration> 

</configuration> 


4. Open and edit the file, as shown in bold in Example 4-14. 

Example 4-14 Application Configuration File for writeToEventLog 

<?xml version="1.0" encodi ng="utf-8" ?> 
<configuration> 

<system.diagnostics> 

<switches> 

<add name=”WriteToEventLog” value=”0”></add> 
</switches> 

</system.diagnostics> 

</configuration> 


The name of the <add> tag is the name given to the switch constructor, not the name of 
the variable representing the switch. The value 0 on the switch indicates that the 
BooleanSwitch is false. Any other value indicates that the switch is true. 

5. Rebuild the project. If your flow is deployed, rebuilding the project will cause a hot-deploy. 

6. In the project folder, under the debug/bin folder, there is now a new .config file named 
after the DLL. Open this file with a text editor or double-click to open it in Visual Studio. 

7. Change the value of the WriteToEventLog switch to 1. Save the file. A hot-deploy occurs 
and the switch is now active. Calls to the logger will output messages to the Event Log. 

You can also use a TextWriterTraceListener class and output your logging information into 
an application-specific file in a known location that is not inside the broker’s working storage 
area. You can configure this file location and enable or disable it in the application 
configuration file, rather than strictly in your code. 

Sample code to add a TextWri terTraceLi stener is shown in Example 4-15 on page 93. 
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Example 4-15 TextWriterTraceListener code example 

Stream logFile = Fi le. Create (“c : \AppLogFi 1 e. txt”) ; 
TextWriterTraceListener tx= new 
TextWri terTraceLi stener(l ogFi 1 e,”myLi stener”) ; 

Trace. Li steners.Add(tx) ; 


You can also add and manage TextWri terTraceLi steners in the Application Config, as 
shown in Example 4-16. 

Example 4-16 TextWriterTraceListener configuration example 

<?xml version= l, 1.0" encodi ng= l, utf-8" ?> 

<configuration> 

<system. di agnosti cs> 

<trace autofl ush=”fal se” indentsize=”4”> 

<1 i steners> 

<add name=”myTextLi stener” 

type=”System. Di agnosti cs .TextWri terTraceLi stener” 
ini ti al i zeData=”c : \textWri terOut . 1 og” /> 

</l i steners> 

</trace> 

</system.di agnosti cs> 

</configuration> 


Using full versus relative paths: The default working directory for your .NET code is the 
Broker’s install directory, by default this is C:\Program Files\IBM\MQSI\8.0.0.0\bin. You 
must ensure that all filenames you use in your .NET code use full paths rather than relative 
paths. Otherwise, you run a strong risk of interfering with the proper functioning of the 
broker by filling up the disk or overwriting files. 


You can also use any other kinds of TraceListener objects, provided they do not write into 
areas that can impact the correct running of the broker. 


4.5 Handling exceptions 

Message Broker V8 uses an exception-based programming model. Nodes that experience 
errors create an exception and pass the exception backwards through the flow by throwing it 
until it is caught by some part of the flow or it reaches the input node that started the flow. 

The .NET API provided for the broker introduces sophisticated features for identifying and 
managing exceptions, both the ones that occur within the .NETCompute node or .NET 
method itself and exceptions that occur downstream of the .NETCompute node. 

Exceptions that are created within a .NETCompute node are treated and caught and handled 
by the native methods in the language being used. Exceptions that are thrown by code inside 
a .NETCompute node and not caught within the node itself are automatically translated into 
Message Broker Exceptions stored in the ExceptionList tree. 

If a .NETCompute node put a try/catch block around the propagate () call that transfers 
control of the message processing to the next node in the flow, any exceptions that occur 
downstream and are not caught get caught by this try/catch block. You can see an example of 
this in Example 4-9 on page 83. The propagate () is included in the try/catch block, so any 
errors that occurred downstream cause the catch code to be executed. In the example, the 
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catch block only tests to see if the error is a specific error that is related to reading the 
message from the Microsoft Messaging Queue. 

If the MQOutput node in the readSales flow throws an exception, it is caught by the 
.NETCompute node. The Message Broker Exception List is parsed and automatically turned 
into an NBException object of the relevant type. The NBException class is a subclass of the 
Microsoft .NET standard Exception class, so it is handled exactly like all other exceptions in 
any .NET program. 

A .NETCompute node can be aware of the failures of processing that occurs downstream of it 
and can make decisions about how to respond to the failure of a message flow as a whole or 
any results that are needed. A .NETCompute node can be wired to the Catch terminal of an 
input node and handle all of the exceptions that occur in the message flow, including rolling 
back any local transactions that are not controlled by the broker or freeing any resources that 
might be locked or affected by the flow. 

You can modify the sample code for the readSales or writeSales code to catch all exceptions 
and then check to see if the caught exception is an NBException object. You can then use this 
object to identify the error that occurred and perform the necessary actions to handle it or 
rethrow it. 


4.6 Sending messages to MSMQ 

In this part of the scenario, we show you how to construct a message flow that gets messages 
(even using different parsers) from a WebSphere MQ queue and forward them onto a MSMQ 
queue. 

4.6.1 Constructing the message flow 

To create a new message flow in your application: 

1 . In the Message Broker Toolkit, create a new message flow in your application and name it 
writeSales. 

2. Construct the message flow using the following steps: 

a. Add an MQInput node from the WebSphere MQ on the Palette. 

b. Add a .NETCompute node from the Transformation folder on the Palette. 

c. Add a Trace node from the Construction folder on the Palette. 

d. Wire the out terminal of the MQInput node to the in terminal of the .NETCompute node. 

e. Wire the failure terminal of the .NETCompute node to the in terminal of the Trace node. 
We will use this just to capture any exceptions that occur. 

Your flow now looks like Figure 4-27. 



Figure 4-27 Message Flow to write to MSMQ 
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4.6.2 Configuring the message flow 


The next step is to configure the relevant properties on the message flow, including adding 
the necessary user-defined properties: 

1 . Select the MQ Input node on the canvas, and specify a queue name of ESB.OUT, as shown 
in Figure 4-28. 


E Properties £3 \ T Problems j E Deployment Log 

MQ Input Node Properties - MQInput 

Description 

Basic Queue name* j ESB.OUT 

Input Message Parsing 
Parser Options 

Figure 4-28 MQInput properties 

2. Create a user-defined property to hold the name of the MSMQ queue. This value is read in 
the OnlnitializeO method: 

a. Select User Defined Properties at the bottom of the Message Flow Editor. 

b. Select Basic, and click the Add Property button. Enter Sal esQueueName, and select 
String as the type to define the name of the queue, as shown in Figure 4-29. 


User Defined Properties 

u 

Iser Property Hierarchy Details 

j j j View and edit the item selected in the property hierarchy. 

kEl-HHU writeSales 
- IH] Basic 

o 

Type | String J 


Default Value | | 

□ Mandatory 




Graph] User Defined Properties 


Figure 4-29 Add SalesQueueName as a user defined property 


c. Switch back to the Graph view. 

3. Select the Trace node on the canvas, and configure the Trace node properties, as shown 
in Figure 4-30. 


D JP Trace Node Properties - Trace 

Description 



Basic 

Destination 

|File 

Monitoring 

File path 

| c:\trace.txt 


Pattern 


*************:ti:ti^_r£|j^p£pj-|- TIME5TAMP}*************** 

${Root} 

$-[ExceptionList}- 


Figure 4-30 Trace node properties 
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4.6.3 Creating the .NET code 


The next step is to create the VisualStudio project and the .NET code associated with the 
.NETCompute node: 

1 . Double-click the .NETCompute node in the message flow to launch Visual Studio. 

2. Select File New Project to create a new project. Follow these steps: 

a. In the Recent Templates column, select Visual C# > Message Broker. 

b. In the list of templates, select Project To Create A Message Broker Message. 

c. In the Name field, enter Wri teQueue . 

d. In the Location field, enter the path to store the project, for example, 
c:\projects\VIStudio. 

e. In the Solution field, Wri teQueue is automatically populated. 

f. Click OK. An editor with the new code template opens. 

3. Add a reference in the project to the System. Messaging component. 

In the Solution Explorer, right-click References, and select Add Reference. In the Add 
Reference window, shown in Figure 4-7 on page 73, select the .NET tab, and then select 
the System Messaging component. Click OK. 

4. In the CreateNode.es code, add the System. Messaging namespace and the 

System. Globalization namespace to the code using statements shown in Example 4-17 to 
the list of using statements at the top of the file. 

Example 4-17 Using statements 

using System. Messagi ng; 
using System. Xml; 
using System. 10; 


5. Save the design by pressing ctrl-S. 

4.6.4 Writing the code 

To create the code for the .NETCompute node: 

1 . The class that is created has a default name of CreateNode. We change the name of the 
class to WriteQueueNode instead. In the Solution Explorer, right-click CreateNode.es and 
select Rename. Enter WriteQueueNode.es, and press Enter. 

When prompted to perform a rename of all references, click Yes. 

2. Create the class variables. 

The salesQueue variable is the MSMQ object representing the queue, and the 
salesQName will hold the actual name of the queue. Add the code shown in bold in 
Example 4-18 to the WriteQueueNode class. 

Example 4-18 WriteQueueNode method 

public class WriteQueueNode : NBComputeNode 

{ 

MessageQueue salesQueue; 

String salesQName; 


3. Create a constructor for the node, as shown in Example 4-1 9 on page 97, directly below 
the variables. 
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Example 4-19 On Initialize method of the node class 

public override void Onlnitial ize() 

{ 

base.0nlnitialize(); 

salesQName = GetUserDefinedPropertyAsString("SalesQueueName") ; 
i f ( IMessageQueue. Exi sts (sal esQName) ) 

{ 

salesQueue = MessageQueue.Create(salesQName) ; 
sal esQueue. Set Permissions ("Users", 

MessageQueueAccessRi ghts . Ful 1 Control ) ; 

} 

el se 

{ 

salesQueue = new MessageQueue (sal esQName) ; 

} 

} 


This code reads the user-defined properties that you created on the message flow, and 
then uses the name property to create and open the MSMQ queue to be used during the 
main flow execution. 

If the broker code created the queue, it also explicitly grants all permissions to all 
members of the Windows group Users. You can still manually create the MSMQ queue 
before the broker flow tries to access it. If you do, ensure that you set the needed 
permissions. The desktop application in 4.2.1 , “Constructing a simple utility to read and 
write MSMQ messages” on page 69 does not set any permissions on the queue, so it is 
automatically private to the user running the application. You can modify the application to 
add the same code to set all permissions, or you can use the Microsoft Server Manager 
console to create the queue and set the appropriate permissions. 

For the purpose of this scenario, the broker creates the queue, giving all users full control. 

4. Having created the constructor, you must create the destructor to make sure that the 
queue is closed when we are finished, as shown in Example 4-20. 

Example 4-20 OnDelete method of the node class 

public override void OnDelete () 

( 

salesQueue. Close() ; 
base.0nDelete() ; 

} 


5. Construct the method you will use to write the message. A skeleton of the Evaluate 
method is already created for you. The Evaluate method handles the messages that arrive 
at the .NETCompute’s Input terminal and allows you to work with the data. When you are 
finished, send it to the MSMQ queue. 

In this step, we show two alternative code options. The first one shows how to receive a 
BLOB message and send it to a MSMQ queue. This option is useful if you want to use 
WebSphere Message Broker as a router with no parsing, simply focusing on performance. 

The second option shows how to code to work with XMLNSC parsed messages. This 
option is useful when you need to handle the data. 

In both code options, we use a basic try/catch block to handle the exceptions. 
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If you choose to work within the BLOB domain, remember to configure the Input Message 
Parsing properties of the MQInput node. Figure 4-31 shows how to configure it to parse 
messages using the BLOB parser. 


Properties X 


2 Problems H Deployment Log 


Jffl MQ Input Node Properties - MQInput 

Message domain | BLOB : For messages with an unspecified format 


Description 


Basic 


Input Message Parsing 


Parser Options 


Advanced 


Validation 


Security 


Message model 
Message 
Physical format 


r 


r 


Figure 4-31 Configuring MQInput to read messages with the BLOB parser 


Select the option to use and add the code in the UserCode region of WriteQueueNode.es. 
Example 4-21 shows the code for BLOB messages. 

Example 4-21 Working with BLOB messages 
#region UserCode 

// Add user code in this region to create a new output message 
// Create the output message structure for a BLOB message, 
try 
{ 

NBElement blobRoot = inputRoot[ l, BLOB M ] ["BLOB"] ; 

Message myMessage = new Message(); 

// Saving the original CCSID and Encoding from the MQ Message 

int oCcsid = (int)inputRoot[ M MQMD"] ["CodedCharSetld"] ; // Original CCSID 

int oEncoding = (int)inputRoot[ l, MQMD M ] ["Encoding"] ; // Original Encoding 

myMessage. BodyStream = new MemoryStream( 

input Root [NBParsers. BLOB. ParserName] . AsBi tStream(oCcsi d,oEncodi ng) ) ; 

sal esQueue. Send (myMessage) ; 

} 

catch (System. Messaging. MessageQueueException e) 

{ 

throw e; 

} 

#region UserCode 


Alternatively, if you choose to work with the XMLNSC domain, remember to configure the 
Input Message Parsing properties of the MQInput node. Figure 4-32 on page 99 shows 
how to configure it. 
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Jffi MQ Input Node Properties - MQ Inputl 

Description 


Basic 

Message domain | XMLNSC : For XML messages (namespace aware, validation, low memory use) 

Input Message Parsing 

Parser Options 


Message model 


Advanced 

Message 

Validation 

Physical Format 

Security 



Figure 4-32 Configuring MQInput to read messages with the XMLNSC parser 


Example 4-22 shows the code for XMLNSC messages. 

Example 4-22 Working with XMLNSC messages 
#region UserCode 

// Add user code in this region to create a new output message 
// Create the output message structure for a XML message, 
try 
{ 

NBElement xml Root = i nputRoot ["XMLNSC"] ; 

Xml Document myMessage = new Xml Document () ; 

// Saving the original CCSID from the MQ Message 
int oCcsid = (int)inputRoot["MQMD"] ["CodedCharSetld"] ; 

// Loading the xml 

myMessage. LoadXml (Encodi ng.UTF8.GetStri ng( 

i nputRoot [NBParsers. XMLNSC. ParserName] .AsBi tStream(0, 

oCcsid))) ; 

sal esQueue. Send (myMessage) ; 

} 

catch (System. Messagi ng.MessageQueueExcepti on e) 

{ 

throw e; 

} 

#region UserCode 


6. Save and close the Wri teQueueNode . cs file. 

7. Select Build -» Build Solution. 

Updating the .NETCompute node 

Now that you have the code, you must update the message flow to use it: 

1 . In the Message Broker Toolkit, click the .NETCompute node. 

2. In the Properties view, select the Basic tab: 

a. In the Assembly name field, browse to the following location and select the 
WriteQueue.dll file: 

C:\projects\VIStudio\Wri teQueue\Wri teQueue\bin\Debug\Wri teQueue.dl 1 

Click Open. 

b. Enter Wri teQueueNode as the class name. 
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3. Select the Advanced tab in the Properties view, and enter Wri teSal es in the AppDomain 
name. This process ensures that this .NETCompute node’s DLL is loaded in another .NET 
application domain and does not interfere with other flows in the same Broker Application. 

4. Save the message flow by pressing Ctrl-S. 

Testing the message flow 

To test the message flow: 

1 . Update the BAR file to deploy your message flow application. Open the BAR file created in 
“Testing the message flow” on page 85 in your Broker Application Development 
perspective, as shown in Figure 4-33. On the Prepare tab, both message flows are listed. 


HD writeSales. msgf low 


Prepare 

Select deployable resources to include in the broker archive 


Deployable Resources 

Select an application to package all its contained resources. Resources within an application are isolated from other 
applications. 

© Applications O Message flows, libraries and other message flow dependencies 
Text filter: |type filter text 


Build and Save... 


- 0 H§ Applications 

- 0 H salesConnector 

- Flows 

j- UHlreadSales. msgf low - /salesConnector/readSales.msgflow 
i- m writeSales. msgf low - /salesConnector/writeSales.msgflow 


Figure 4-33 Updating the sales.bar File 


Click Build and Save. 

2. Switch to the Manage tab. Expand your application, and select the writeSales compiled 
message flow, as shown in Figure 4-34. 


Name 

- H salesConnector 
ED H readSales.cmf 
- HHH writeSales. cmf 
□ H writeSales 
.NETCompute 

Figure 4-34 Select the message flow to edit the deployable properties 

3. In the Properties view, set the SalesQueueName to .\private$\SALESIN to indicate an 
MSMQ queue on the local machine in the private area named “salesin”, as shown in 
Figure 4-35 on page 101. 
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L— Properties £3 [j Problems | ffl Deployment Log 

writeSales 

1 

Configure 

(T) Configure properties of selected built resource. 


5alesQueueName | .\private|\5ALE5IN 




Figure 4-35 Edit the deployable properties 


4. Save the BAR file and redeploy it by dragging it onto the execution group in your local 
broker. 

If the BAR file does not deploy, a message is displayed with the option to view the details 
of the error. The information gives you an idea of the problem. If the .NETCompute node is 
called out as the problem, review the settings in “Updating the .NETCompute node” on 
page 99. If so, update the settings and then rebuild and deploy the bar file. 

You can see that your queue is created in the Server Manager view, as shown in 
Figure 4-36. (You might need to refresh the view.) 



Figure 4-36 New queue visible in Server Manager 

Note that MSMQ forced the name of the queue into lowercase. 

5. Use the WebSphere MQ Explorer to put a message into the ESB.OUT queue. 

In the WebSphere MQ Explorer - Navigator view, expand the queue manager, and select 
Queues. In the Content pane, right-click ESB.OUT and select Put Test Message. 

Example 4-23 shows a sample message that works for both domains. Enter the message, 
and click Put message. 

Example 4-23 Sample queue message 

<sal esorder><product number=" 12345"><pri ce>150</pri ce><descri pti on>A beauti ful 
new leather wal let</description></product></salesorder> 


Note: MSMQ messages are limited to 4 Mb of data and do not support message 
segmentation, unlike IBM WebSphere MQ. For messages larger than 4MB, you must 
split the message into smaller messages using your own coding techniques. Make sure 
that both sender and receiver know about the split mechanism. 


6. Use the Server Manager to view the message on the queue. Right-click the salesin 
queue, and select Refresh, as shown in Figure 4-37 on page 102. 
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Figure 4-37 Checking the message in the salesin queue 

If you do not see a message on the queue, make sure that your input message parsing 
property on the MQ Input node matches the code type that you selected for your 
.NETCompute node (BLOB or XMLNSC). Also make sure that you used valid data, as 
shown in Example 4-23 on page 101. 

7. Double-click the message in the viewer to check the body of the message, as shown in 
Figure 4-38. 


Properties 


General | Queues | Sender Body 
The body size is 1 79 bytes. 


<?xml version = 11 1 . 0 11 ?> 

<salesorder> 

<product number= 11 12345 11 > 

<price> 150</price> 
<description>A beauti 
</product> 

</salesorder> 


3 


iL 


J 


□ K 


Cancel 


Apply 


Figure 4-38 Checking the Body of the message 
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4.7 Distributed transactional coordination 


A business transaction is a set of tasks that either succeed or fail as a unit. Although tasks 
that are associated with a transaction are operationally independent, they share a common 
intent as a unit. By performing only a subset of these operations, the system can compromise 
the overall intent of the transaction. 

To guarantee the “all or nothing” aspect of transactions, the IT systems must handle 
participating operations in a transactional context within the overall scope. If a single 
participant of the transaction fails, all changes to data within the scope of the transaction are 
rolled back to a previous stage. All participating operations must guarantee that any change 
to data is permanent and will persist despite system crashes or other unanticipated events. 

Although updates made using the .NET languages do not participate in WebSphere Message 
Broker transactions, it is possible to use transactions with MSMQ manually. This means that 
the developer controls the transaction and must be aware of the constraints. We will show 
how to do a manual transaction by performing some changes to our message flow. 


4.7.1 Manual transaction sample 

Our example uses the writeSales message flow to illustrate how to commit/rollback a 
transaction: 

1 . Open the writeSales message flow, and add another .NetCompute node after the first 
.NETCompute node, and rename it to Commit. 

2. Wire the out terminal of the .NETCompute node to the input terminal of the Commit node. 
Wire the failure terminal of the Commit node to the Trace node. Your flow now looks like 
Figure 4-39. 



Figure 4-39 Changing the flow to add manual transaction 


3. Declare a static MessageQueueTransaction variable inside the WriteQueueNode class, as 
shown in bold in Example 4-24. 

Example 4-24 Defining the static MessageQueueTransaction variable 

public class WriteQueueNode : NBComputeNode 

{ 

MessageQueue sal esQueue; 

String salesQName; 

public static MessageQueueTransaction tx; 

public override void Eval uate(NBMessageAssembly i nputAssembly) 

{ 

(...) 
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4. To determine that our MSMQ queue supports transactions, change the constructor of the 
node, adding a new parameter with value true in the Create method, as shown in bold in 
Example 4-25. 

Example 4-25 Onlnitialize method of the node class 

public override void On Initial ize() 

{ 

base.Onlnitial ize() ; 

sal esQName = GetUserDef i nedPropertyAsStri ng ( "Sal esQueueName" ) ; 
if (IMessageQueue.Exi sts (sal esQName)) 

{ 

salesQueue = MessageQueue.Create(salesQName, true); 
sal esQueue.SetPermi ssi ons ("Users" , 

MessageQueueAccessRi ghts .Full Control ) ; 

} 

el se 

{ 

salesQueue = new MessageQueue(sal esQName) ; 

} 

} 


5. Add code to begin the transaction before you send the message. The code is highlighted 
in Example 4-26. 

Example 4-26 Doing manual transaction between WebSphere Message Broker and MSMQ 
#region UserCode 

// Add user code in this region to create a new output message 

try 

{ 

NBElement xml Root = inputRoot["XMLNSC"] ; 

Xml Document myMessage = new Xml Document () ; 

int oCcsid = (int)inputRoot["MQMD"] ["CodedCharSetld"] ; 
myMessage. LoadXml (Encodi ng.UTF8.GetStri ng( 

i nputRoot [NBParsers.XMLNSC. ParserName] .AsBi tStream(0, 

oCcsid))) ; 

tx = new MessageQueueTransaction() ; 
tx.Begin() ; 

salesQueue. Send (myMessage, tx) ; 

} 

catch (System. Messagi ng.MessageQueueExcepti on e) 

{ 

throw e; 

} 

#region UserCode 


6. Add a new class to the Project: 

a. Select Project Add Class. 

b. Select Message Broker -> Class to create a Message Broker. 
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c. Name the new class Commi tNode. 

d. Click Add. 

7. In the Solution Explorer, right-click CreateNode.es and select Rename. Enter 
CommitNode.es and press Enter. 

8. Enter the code shown in Example 4-28 in the UserCode region to test committing the 
transaction. 

Example 4-27 Defining the static MessageQueueTransaction variable 
Iregion UserCode 

// Add user code in this region to modify the message 
// Manually commits the transaction 
WriteQueueNode.tx.Commit() ; 

#endregion UserCode 


9. Alternatively, you can test the rollback scenario. Enter the code in Example 4-28 to 
rollback the transaction. 

Example 4-28 Defining the static MessageQueueTransaction variable 
Iregion UserCode 

// Add user code in this region to modify the message 
// Manually rollbacks the transaction 
WriteQueueNode.tx.Abort() ; 
lendregion UserCode 


10. Save and close the CommitNode.es file. 

1 1 .Select Build -» Build Solution. 

1 2. In the Message Broker Toolkit, select the Commit .NETCompute node, and on the basics 
tab, complete the assembly name field with a pointer to the WriteQueue dll. 


4.7.2 Testing the message flow 

At this point, you can execute tests committing or rolling back your messages. You can check 
the Computer Management Console in Windows to see if the messages are being committed 
or rolled back: 

1 . Update the BAR file to deploy your message flow application. Open it in your Broker 
Application Development perspective. See Figure 4-40 on page 106. Click Build and 
Save. 
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HHH writeBales.msgflow 


Prepare 

Select deployable resources to include in the broker archive 


Deployable Resources 

Select an application to package all its contained resources. Resources within an application are isolated from other 
applications. 

© Applications O Message flows, libraries and other message flow dependencies 
Text filter: |type filter text 


pff Build and Save... 


E-0 C3 Applications 

- El O salesConnector 
[=]■ Flows 

j- HireadSales.msgflow - /salesConnector/readSales.msgflow 
1- HHiwriteSales.msgflow - /salesConnector/writeSales.msgflow 


Figure 4-40 Updating the sales.bar File 


2. Switch to the Manage tab. Expand your application, and select the writeSales compiled 
message flow. See Figure 4-41 . 


Name 

- [a| salesConnector 
+ HO readSales.cmf 
- WM writeSales. cmf 
-] mH writeSales 
.{^ .NETCompute 

Figure 4-4 1 Select the message flow to edit the deployable properties 

3. In the Properties view, set the SalesQueueName to a valid UNC path that names the 
correct queue. For the purposes of this scenario, use .\pri vate$\SALESIN.TX to indicatea 
transactional queue on the local machine in the private area named salesin.tx. See 
Figure 4-42. 


Problems H Deployment Log 

writeSales 




Configure 

(T) Configure properties of selected built resource. 


BalesQueueName | .\private|\5ALE5IN.TX 


Figure 4-42 Edit the deployable properties 


4. Save the bar file, and deploy it by dragging it onto the execution group in your local broker. 

5. You can see that your queue is created in the Server Manager view, as shown in 
Figure 4-43 on page 107. (You might need to refresh the view.) 
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Figure 4-43 New Queue visible in Server Manager 

6. You can now put a message into the ESB.OUT queue. Example 4-29 shows a sample 
message. 

Example 4-29 Sample queue message 

<sal esorderxproduct number=" 12345"><pri ce>150</pri ce><descri pti on>A beauti ful 
new leather wal let</description></product></salesorder> 


7. Use the Server Manager to view the message on the queue. Right-click the salesin.tx 
queue and select Refresh, as shown in Figure 4-44. 



Figure 4-44 Checking the message in the salesin queue 

8. Double-click the message in the viewer to check the message body. See Figure 4-45 on 
page 108. 
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Properties 


mml 


General | Queues | Sender Body | 
The body size is 1 79 bytes. 


<?xml version = 11 1 . 0 11 ?> 

<salesorder> 

<product number= 11 12345 11 > 

<price> 150</price> 
<description>A beauti 
</product> 

</salesorder> 


3 


iL 


if 1 


□ K 


Cancel 


Apply 


Figure 4-45 Checking the Body of the message 
If you see the message, the commit worked. 


4.8 Conversions 

Messages coining from Z/OS, IBM AIX®, Linux, Windows, or any other platform that is 
supported by IBM WebSphere MQ or coming from other countries with code pages that are 
specific to national languages or operating systems can require encoding and CCSID 
conversions. Basically, CCSID conversion is used to convert character data and control 
characters, while encoding conversion does it for numeric data. You can find more information 
about CCSID and encoding conversions in the WebSphere MQ documentation at: 

http : //www-01 . i bm.com/ support/docvi ew.wss?ui d=swg27005729 
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Scenario: Calling Microsoft 
Dynamics CRM from a message 
flow 


This chapter explores the integration capabilities of message flows and Microsoft Dynamics 
CRM. This scenario is based on a WebSphere Message Broker message flow that connects 
to an SAP system, a database, and Microsoft Dynamics CRM Online. 

This chapter contains the following topics: 

► Scenario overview 

► Creating the message flow 

► Deploying the message flow 

► Testing the message flow 

► Troubleshooting tips 


Additional materials: The WebSphere Message Broker project interchange file and the 
.NET class code for this scenario can be downloaded from the IBM Redbooks publication 
web site. See Appendix A, “Additional material” on page 485 for more information. 


© Copyright IBM Corp. 2012. All rights reserved 
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5.1 Scenario overview 


Enterprise applications typically need to integrate data residing on multiple diverse data 
stores, creating the need for a single interface that can connect and integrate heterogeneous 
data stores for transforming the data. 

In this chapter, we explore the WebSphere Message Broker capabilities to connect and 
integrate applications using Microsoft Dynamics CRM, SAP, and Microsoft SQL Server 2008 
databases with an online store scenario. In this scenario, a large online store, whose data 
warehouse is based on an SAP system recently acquired another online store whose data 
warehouse is based on a home-grown database system. After the acquisition, the store wants 
a clean merger with SAP as the master data warehouse and with Microsoft Dynamics CRM 
for their call center service representatives (CSRs) and any front-end user interface 
applications. For example, a customer wants to subscribe to a service with the online store. If 
the customer is an existing customer, their previous customer information must be associated 
with the current request. These existing records can be on the SAP system, the database 
(from the acquisition), or both. This means that we must provide one interface to these 
systems and a consolidated view for better customer service. 

The IT team deployed WebSphere Message Broker connectivity to connect their acquired 
SQL-based home-grown data warehouse and SAP systems with Microsoft Dynamics CRM 
Online. This solution creates a 360-degree view of customers in real time. All account, credit, 
and sales information can now be sent to Microsoft Dynamics CRM Online from the SAP and 
database. 

Figure 5-1 shows the environment. 



Figure 5- 1 WebSphere Message Broker connectivity 


5.1 .1 SAP Request node for SAP Software 

The SAP Request node is an application adapter for SAP Software that connects a message 
flow to SAP using an SAP Java interface called SAP Java connector(JCo). It does so by 
making calls modeled as business objects to the SAP native interfaces and passing data to 
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and from the SAP System. The adapter supports SAP integration interfaces, such as BAPI 
and ALE, and SAP remote function call (RFC) function modules. 


5.1.2 Microsoft Dynamics CRM Online 

Microsoft Dynamics CRM 201 1 /Online is customer relationship management software from 
Microsoft for managing interactions, orders, bills, audits, and satisfaction surveys with the 
sales, clients, and customers. It offers a new level of productivity to sales, services, and 
marketing organizations by providing familiar, intelligent, and connected experiences with rich 
integration features. 

Microsoft Dynamics CRM offers several programming models. In this chapter, we 
demonstrate the WebSphere Message Broker connectivity to Microsoft Dynamics CRM 
Online version by exploring its late-bound programming model. 


5.1 .3 Prerequisites for this scenario 

Before reading this chapter, you must be familiar with the following products: 

► IBM WebSphere Message Broker 

► IBM WebSphere MQ 

► SAP Software 

► Microsoft Dynamics CRM 

To follow the instructions for the technical examples described in this chapter, you must have 
a development environment set up and running that includes: 

► WebSphere Message Broker Runtime and WebSphere Message Broker Toolkit V8.0 

► WebSphere MQ V7.0.1 

► Access to an SAP environment 

► Access to Microsoft Dynamics CRM Online 

► Microsoft CRM SDK 

http://www.mt crosoft.com/en-us/download/detai 1 s.aspx?i d=24004 

► Windows Identity Foundation 

http://www.mi crosoft.com/downl oad/en/detai 1 s .aspx?i d= 17331 

► Microsoft Visual Studio 2010 


5.2 Creating the message flow 

The message flow in this scenario handles customer requests to subscribe to a service with 
the online store. 

If the customer is an existing customer, the message flow verifies the customer records from 
SAP and the database and create a new CRM Customer record by tagging-in the account 
numbers from SAP and the database. 

If the customer is a new customer, the message flow creates a new SAP customer record. 
The message flow then verifies the customer record in the database and creates a new CRM 
Customer record by tagging-in the account numbers from SAP and the database. 
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Integration scenarios and options vary based on business needs, for example, this scenario 
explores connectivity to Microsoft Dynamics CRM Online using a late-bound programming 
model. You can also use an early-bound or other programming models. WebSphere MQ is 
used as the transport between WebSphere MQ and Microsoft Dynamics CRM. Based on the 
front-end architecture and connectivity, you might consider designing the front-end 
application to send SOAP requests or HTTP requests instead of WebSphere MQ messages. 
It is also possible to use Microsoft Message Queuing (MSMQ) as the messaging engine for 
this flow. For more information about calling WebSphere Message Broker integration with 
MSMQ, see Chapter 4, “Scenario: Bridging WebSphere MQ and Microsoft Message 
Queuing” on page 67. 

Figure 5-2 shows the WebSphere Message Broker flow for this scenario. 



The following list describes the behavior of each node. 

1 . WebSphere MQ messages enter the flow through the Flowlnput node. 

2. The FilterRequest node determines if the request is from an existing or new customer. It it 
is from a new customer the message is sent to the SAP Create node. If it is from an 
existing customer, the message is sent to the SAP Retrieve node. 

3. The SAP Retrieve node retrieves the Customer records from the SAP system based on a 
customer number search. 

4. The SAP Create node creates a new customer record on the SAP system based on a 
reference customer. 

5. The SAP Update node updates the newly created customer record with field values. 

6. The AddCustDetails node constructs the SAP request to update the customer details. 

7. The CatchSAPErrors node processes SAP errors and creates a meaningful exception 
message. 

8. The CatchFlowErrors node processes flow errors and creates a meaningful exception 
message. 

9. The FlowErrors node stores the error messages that occur during flow execution. 

10. The SAPErrors node stores the error messages that occur during SAP system 
interactions. 

1 1 .The .NET/CRM Errors node stores the error messages that occur during database and 
CRM interactions. 

12. The FlowOutput node stores the message flow execution output. 

13. The DB CreateCRMOnlineCustomer node interacts with the database and creates the 
customer on CRMOnline. 
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Additionally, Figure 5-2 on page 112 shows the following flow details: 

1 . When an MQ message with data conforming to XMLNSC format is placed on the input 

queue, the Flowlnput node picks up the message and passes it to the .NETCompute 

FilterRequest node. 

2. The FilterRequest node checks for the type of request (New Customer / Existing 

Customer) and routes the message accordingly to the SAP Retrieve or SAP Create 

nodes. 

3. If the message is sent to the SAP Retrieve node: 

a. The SAP Retrieve node uses the customer number in the incoming message and 
constructs a SapBapiCustomerGetdetaill request. It issues a BAPI call and gets the 
customer details and passes them to the .NETCompute node 
DB<->CreateCRMOnlineCustomer. 

b. The DB<->CreateCRMOnlineCustomer node checks if the customer exists in the 
database by performing a search based on the customer email ID. If the customer 
exists, it retrieves the DB account number and then creates a new CRM online 
customer with a reference to SAP and the database account numbers. 

c. The DB<->CreateCRMOnlineCustomer node sends an output message of format 
XMLNC to the FlowOutput node which places the new message on the output queue. 
The CRM online record identifier is included in the message. 

4. If the message is sent to the SAP Create node: 

a. The SAP Create node uses the data from the incoming message to construct a 
SapBapiCustomerCreatefromdatal request. The node issues a BAPI call, gets the 
customer details, and passes that information to the Compute Node AddCustDetails. 

b. AddCustDetails constructs a SapBapiCustomerChangefromdatal request with the 
new customer details and sends the request to the SAP Update node. 

c. The SAP Update node uses the information coming in from the Compute node and 
issues a BAPI call to update the Customer details, then passes the returned values to 
the .NETCompute node DB<->CreateCRMOnlineCustomer. 

d. The DB<->CreateCRMOnlineCustomer node checks if the given customer exists in the 
database by performing a search based on the customer email ID. If the customer 
exists, it retrieves the database account number and then creates a new CRM online 
customer with a reference to SAP and the database account numbers. 

In the following sections, we implement these steps by creating the message flow from the 

beginning and exploring the techniques used to integrate with SAP and Microsoft Dynamics 

CRM. We also test our message flow to see if it can retrieve/create data from SAP to 

Microsoft Dynamics CRM Online. 

This section tells you how to create this message flow using the following steps: 

► Setting up the environment 

► Creating and connecting the nodes 

► Configuring the node properties 

► Broker configuration for SAP request nodes 

► Writing the code for the SAP nodes 

► Coding the ESQL for the Compute nodes 

► Coding the Filter Request .NETCompute node 

► Writing the code for the database operations 

► Writing the code for accessing Microsoft Dynamics CRM Online 

► Writing the code for the .NETCompute node (Create) - DB<->CreateCRMOnlineCustomer 
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5.2.1 Setting up the environment 


Use this section to help you create the WebSphere MQ, WebSphere Message Broker, SQL 
Server, and SAP environments for messaging. 

WebSphere Message Broker 

Use the Message Broker Toolkit or the WebSphere Message Broker Explorer to create a new 
broker instance called SAMPLEBROKER. Specify SAMPLEQM as the queue manager. 

WebSphere MQ 

Use the WebSphere MQ Explorer to create the following local queues on SAMPLQM. 

► INPUT_MSGS_Q 

► FLOW_ERROR_MSGS 

► SAP_ERROR_MSGS 

► DotNet_CRM_ERROR_MSGS 

► OUTPUT_MSGS_Q 

SQL Server database 


Working with SQL Server: This section assumes that you have SQL Server running on 
the same system as Visual Studio. Instructions for enabling SQL Server database are in 
8.3.1 , “Creating the database” on page 396. 


This scenario uses a Microsoft SQL Server 2008 database called ITSOCRM that has the 
following two tables. 

Customers table with the columns shown in Table 5-1 . 


Table 5-1 Customers table 


Column 

Datatype 

customerid 

uniqueidentifier, 
primary key, 

DEFAULT 

NEWSEQUENTIALID() 

firstname 

varchar(IOO) 

lastname 

varchar(IOO) 

addressl 

varchar(IOO) 

address2 

varchar(IOO) 

city 

varchar(50) 

state 

varchar(50) 

country 

varchar(50) 

postal code 

varchar(IO) 

email 

varchar(250) 

phone number 

integer(IO) 

modified date 

DateTime 
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Accounts table with the columns in Table 5-2. 


Table 5-2 Accounts table 


Column 

Datatype 

account number 

UNIQUEIDENTIFIER 

DEFAULT 

NEWSEQUENTIALID() 
PRIMARY KEY 

customerid 

UNIQUEIDENTIFIER 

DEFAULT 

NEWSEQUENTIALID() 
PRIMARY KEY 

email 

varchar(250) 

modified date 

DateTime 


SAP environment 

Obtain the SAP Java connector files (sapjco3. jar, sapjco3.dl 1) from the SAP system or the 
SAP administrator and copy them to your local drive. In our scenario, we used C:\SAP_JC0 as 
our location. 


5.2.2 Creating and connecting the nodes 

Use the following procedure to construct the skeleton of the message flow using the Message 
Broker nodes: 

1 . Create a directory file that is created or copied for the message flow. In our scenario, we 
created the directory C:\SampleFlow. 

2. Start Message Broker Toolkit V8.0, and create a new application and message flow. 

3. Using the information in Table 5-3, add and wire the nodes to the message flow. As you 
build the message flow, use Figure 5-2 on page 1 12 as a reference. 


Table 5-3 Nodes used to create the message flow 


Palette drawer / node 
type 

Node name 

Wiring information (terminal to node) 

WebSphere MQ 

MQInput 

Flowlnput 

► Out: FilterRequest 

► Catch: CatchFlowErrors 

► Failure: CatchFlowErrors 

Transformation 

.NETCompute 

FilterRequest 

► Failure: CatchFlowErrors 

► Out: SAP Retrieve 

► altOut 1 : SAP Create 

WebSphere Adapters 

SAPRequest 

SAP Retrieve 

► Failure: CatchSAPErrors 

► Out: DB<->CreateCRMOnlineCustomer 

WebSphere Adapters 

SAPRequest 

SAP Create 

► Failure: CatchSAPErrors 

► Out: AddCustDetails 

Transformation 

Compute Node 

AddCustDetails 

► Out: SAP Update 

1 You must add the altOut terminal to the node. Right-click the node, and select Add Output Terminal. Enter the 
name of the new terminal. 
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Palette drawer / node 
type 

Node name 

Wiring information (terminal to node) 

WebSphere Adapters 

SAPRequest 

SAP Update 

► Failure: CatchSAPErrors 

► Out: DB<->CreateCRMOnlineCustomer 

Transformation 

Compute Node 

CatchSAPErrors 

► Out: SAPErrors 

Transformation 

Compute Node 

CatchFlowErrors 

► Out: FlowErrors 

WebSphere MQ 

MQOutput 

FlowErrors 

(none, end of flow) 

WebSphere MQ 

MQOutput 

SAPErrors 

(none, end of flow) 

WebSphere MQ 

MQOutput 

.NET/CRM Errors 

(none, end of flow) 

WebSphere MQ 

MQOutput 

FlowOutput 

(none, end of flow) 

Transformation 

.NETCompute 

DB<->CreateCRMOnlineCustomer 

► Failure: .NET/CRM Errors 

► Out: FlowOutput 

1 You must add the altOut terminal to the node. Right-click the node, and select Add Output Terminal. Enter the 
name of the new terminal. 


5.2.3 Configuring the node properties 

The next step is to configure the node properties. 

WebSphere MQ nodes 

Use the following procedure to configure the Flowlnput node. 

1 . Select the Flowlnput node on the canvas, and open the Properties view. 

2. On the Basic tab, enter INPUT_MSGS_Q as the queue name, as shown in Figure 5-3. 

DJEi MQ Input Node Properties - Flowlnput 

Description 

Basic Queue name* INPUT_MSGS_Q 

Input Message Parsing 

Figure 5-3 MQInput node Queue Name 

3. On the Input Message Parsing tab, select XMLNSC: For XML messages (namespace 
aware, validation, low memory use) from the drop-down list on the Message domain 
field, as shown in Figure 5-4 on page 117. 
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□ Properties E-S ' 


0# MQ Inpul Node Properties - Flowlnput 


Description 


Basic 

Input Message Parsing 

Message domain XMLNSC : For XML messages [namespace aware; validation, low memory use) 

Messaae model 


Figure 5-4 MQInput node Message domain 


4. Select each MQ Output node, and on the Basic tab of the Properties view, enter their 
queue name: 

- FlowErrors node: queue name FLOW_ERROR_MSGS 

- SAPErrors node: queue name SAP_ERROR_MSGS 

- .NET/CRM Errors node: queue name DotNet_CRM_ERROR_MSGS 

- FlowOutput node: queue name OUTPUT_MSGS_Q 

5. Press Ctrl+S to save your changes. 

.NETCompute nodes 

The .NETCompute node is configured with the location of the .NET assembly. In our scenario, 
we use a .NET assembly called MBCreateCRMOnl i ne and its classes, FilterRequest and 
CreateCRMOnline. 

1 . Double-click the FilterRequest node to open Visual Studio. 

2. In Visual Studio, select File -» New Project. 

a. Select Visual C# > Message Broker and Project to filter a Message Broker 
message. 

b. Enter MBCreateCRMOnl i ne as the project and solution name. 

c. Enter a location for the project. 

d. Click OK. 

3. From the Solution Explorer, rename the Filternode.es to Fi lterRequest.es. 

4. From the Solution Explorer, right-click the project, and select Add Class. The Add New 
Item screen displays: 

a. Select Message Broker and Class to create a Message Broker message. 

b. EnterCreateCrmOnline.es in the Name field. 

c. Click Add. 

The Project tree in the Solution Explorer now looks like Figure 5-5 on page 118. 
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Figure 5-5 CreateCrmOniine.es class 

5. Save all files by pressing Ctrl+Shift+S, and build the project by selecting Build Build 
Solution. This action generates a .NET assembly called MBCreateCRMonline.dll under 
the project\bin\debug directory. 

The Output view shows the full directory path for the output. 

Build started: Project: MBCreateCRMOnl ine, Configuration: Debug Any CPU 

MBCreateCRMOnl i ne -> 

C : \Sampl eFl ow\MBCreateCRMOnl i ne\MBCreateCRMOnl i ne\bi n\Debug\MBCreateCRMOnl i ne . dl 1 

========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ========== 

The code for the .NET project is created later. For now, all we need to configure the 
.NETCompute node is an existing dll file. 

6. Switch back to the Message Broker Toolkit. 

7. In the message flow, select the FilterRequest node. In the Properties view of the Basics 
tab, enter the Assembly name. This is the fully qualified path of the dll file: 

C:\SampleFlow\MBCreateCRMOnl i ne\MBCreateCRMOnl i ne\bi n\Debug\MBCreateCRMOnl i ne.dl 1 

Enter Fi 1 terRequest as the Class name. 

The results are shown in Figure 5-6. Save your changes by pressing Ctrl+S. 


Properties £3 £ Problems EH Deployment Log 

.{JJ .NETCompute Node Properties - FilterRequest 

Description 


Basic 

Assembly name* | C : \5ampleFlow\MBCreateCRMOnline\MBCreateCRMOnline\bin\Debug\MBCreateCRMOnline . dll 

Visual 5tudio 
Advanced 

Class name f FilterRequest 



Figure 5-6 FilterRequest properties 


8. Repeat step 7 to define the properties for the DB<->CreateCRMOnlineCustomer node. 
Use the same value for the Assembly name field and enter the Class name as 
CreateCrmOnl i ne. 
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Compute node 

Use the following procedure to create projects and define properties for the following 
Compute nodes we defined for this scenario: 

► AddCustDetails 

► CatchFlowErrors 

► CatchSAPErrors 

1 . For each Compute node, open the Properties view, and select the Basic tab. 

2. Select the Compute mode as LocalEnvironment and Message. 

3. Leave all of the other default settings, and press Ctrl+S to save the properties for each 
node. 

The ESQL for the Compute nodes is created in later sections. 

SAPRequest nodes 

WebSphere Adapters allow the message flow to communicate with Enterprise Information 
Systems, including SAP. The SAPRequest nodes used in this flow support the use of the 
WebSphere Adapter for SAP. 

To configure the SAP request nodes: 

1 . Right-click the SAPRetrieve node, and select Open Adapter Component to open the 
Adapter Component Select panel shown in Figure 3. 



Figure 5- 7 Select an adapter component 

2. Click the Import/Create New link at the bottom of the screen in Figure 5-7. 

3. In the Figure 5-8 on page 120, select IBM WebSphere Adapter for SAP Software with 
transaction support, and click Next. 
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Adapter Connection 


Configure Settings for Discovery Agent 

Specify the properties to initialize the discovery agent. 


JT\ 

Wy 1 




IBM WebSphere Adapter for SAP Software with transaction support 


d 


(?) 


Figure 5-8 Create an adapter connection 

4. In the Connector Import screen (Figure 5-9), accept the name provided in the Connector 
project field, and click Next. 


< Back 

Next > 1 

Finish 

Cancel 


1 

1 




Figure 5-9 Create a connector project 

5. The connector is built and Figure 5-10 on page 121 displays. Enter the paths and file 
names for the SAP jar and dll file, as shown. Click Next. 
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D Adapter Connection 




Connector Settings 

Select dependency libraries and jars for the connector project. 


f T* 


lid 


Specify the location of the files required to access the SAP server. You might first need to contact your SAP system 
administrator to download these files from the SAP Web site. 

SAP sapjco3. jar file: * | C : \S AP_JCO\sap jco3 . jar Browse... 

System library file (sap jco3 . dll or libsap jco3 . so) : * | C:\SAP_JCO\sapjco3.dll Browse . . . 


1 f < Back | [ Next > || Finish | Cancel 

Figure 5-10 Connector files 

6. Enter the host name, user name, and password required to connect to the SAP system. 
Specify BAPI as the SAP interface name, as shown in Figure 5-1 1 . Click Next. 

The values in Figure 5-11 are example values. Flost name, system number, client, user 
name, and password are specific to your SAP system. 



Figure 5-11 Configure the connector 
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7. On the next screen, Figure 5-12, you discover services that are available on the system 
that you are connected to. In this scenario, the SAP nodes tries to retrieve or create 
customer information using the BAPI interface, which is available in the Business Object 
Repository (BOR) object. 

Select BOR, and click the Filter button. Apply a filter to narrow your search on the BOR. In 
this case, we use Customer1533. Click OK. 


IH Adapter Connection 


Find and Discover Services 


HiD 


Expand nodes to view and select discovered objects. Use filtering, if necessary 
to limit number of objects displayed. 




Objects discovered by query: 


Objects to be imported: 


a* a. co 


+ RFC 
BOR 


✓ 


111 Adapter Connection 


Filter Properties for 'BOR 1 

5et the filter properties, then press OK to apply the filter. 


Find objects with this pattern :* u ] ^UBTOMERlBBBj* 


\ <Z 


El 




OK Cancel 


B 


< Back Next > Finish Cancel 


Figure 5-12 Apply a filter 


8. In the Objects discovered by query column, click expand BOR to see the objects 
discovered by the search. 

9. Select the desired object and expand the view on it. 

In our example, we need BAPIs to create, get, and change the customer details from the 
SAPCreate, SAPRetrieve, and SAPUpdate nodes. 

Select the BAPI objects and move them to the Objects to be imported column, as shown in 
Figure 5-13 on page 123. As you click the JT|J button to move each object, a configuration 
panel opens. Click OK on that panel: 

- BAPI_CUSTOMER_CHANGEFROMDATA1 

- BAPI_CUSTOMER_CREATEFROMDATA1 

- BAPI_CUSTOMER_GETDETAIL1 
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Figure 5-13 Select the BAP I objects to be imported 


After you move all of the objects to the right column, click Next. 

10. In the Configure Objects screen, verify the business object namespace, and select 
Synchronous RFC for the SAP call type, as shown in Figure 5-14. Click Next. 



Figure 5-14 Specify object configuration properties 

11. On Figure 5-15 on page 124, you set properties for service generation and deployment. 
Verify and complete the connection properties to be used for the SAP system at run time, 
and click Next. 
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!□ Adapter Connection 


HUE 


Service Generation and Deployment Configuration 

^ Password: Sensitive values, such as passwords, should not be saved. 



Service Operations 

To modify the names, or add a description to the operations to be generated operations 
in the interface file, click Edit Operations. . 

Deployment properties 

Specify the connection properties which will be used to connect to the Enterprise Information 
System at runtime: 

Connection Properties 


SAP system connection information 
I - Use load balancing 

To use load balancing, specify the load balancing properties in the Additional 
connection configuration panel under the Advanced tab. 


| WMBSAP 


Host name: 

System number: |~00 
Client: [Too 

Language code: EN (English) 

Code page: 


Select.. 


1100 


~3 


User name: 
Password: 
Advanced >> I 


SAPUSER 


zi 


* 

Figure 5-15 Service generation and deployment configuration properties 

12. On the last screen of the wizard, Figure 5-16 on page 125, set properties for creating and 
running the connector. Set the adapter component name. In this scenario, we use 
SapCustomerOutbound. Verify the remaining properties, and click Finish. 


< Back 

Next > 

Finish 

Cancel 




J 
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Figure 5-16 Publishing properties for the adapter 

13. After the adapter connection wizard is complete, update the SAPRequest nodes (SAP 
Retrieve, SAP Create, and SAP Update) on the message flow with the adapter connection 
information. 

To do this, select each node and open the Basic tab in the Properties view: 

a. Select the SAP Retrieve node, as shown in Figure 5-17. 

The Browse button provides a list of adapter components to choose from. The values 
are determined by the publishing properties that you set in Figure 5-16. 

Select Adapters/SAP/SapCustomerOutbound.outadapter. 

b. After you select the adapter, the drop-down list for the Default Method provides a list of 
methods to choose from. Select executeSapBapiCustomerGetdetaill. 


Properties £3 

zi ^ " □ 

mb SAP Request Node Properties - SAP Retrieve 



Description 


Basic 


Response Message Parsing 


Transactionality 


Request 


Result 


Monitoring 


Primary adapter component* 
Secondary adapter mode 
Default method* 


| Adapters/5 AP/5apCustomerOutbound . outadapter 
[None 


j executeSapBapiCustomerGetdetail 1 


Browse., 


~3 


Figure 5-17 Define SAP Retrieve node properties 


c. Open the SAP Create node properties, as shown in Figure 5-18 on page 126. The 
primary adapter component is the same as the primary adapter component for the 
SAP Retrieve node. Select executeSapBapiCustomerCreatefromdatal as the 
default method. 
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^ Properties [i v D S 

mb SAP Request Node Properties - SAP Create 



Description 

Basic 

Primary adapter component* | Adapters/5AP/5apCustomerOutbound.outadapter Browse... | 

Response Message Parsing 

Secondary adapter mode ||None 

Transactionality 

Request 

Default method* | executeSapBapiCustomerCreatef romdata 1 

Result 


Monitoring 



Figure 5-18 Define SAP Create node properties 


d. Open the SAP Update node properties, as shown in Figure 5-1 9. The primary adapter 
component is the same as the primary adapter component for the SAP Retrieve node. 
Select executeSapBapiCustomerChangefromdatal as the default method. 



After all of the SAPRequest nodes are updated, the list of schema definitions for the 
application in the Broker Development view will look like Figure 5-20 on page 127. 
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Application Development 


New... 


a ^ Sample 

a Q&, Schema Definitions 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p b a p i c u sto m ere h a n g ef ro m d atal 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p b a p i c u sto m ere reatef ro m d atal 

t> http ://www. i b m . e o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p b a p i c u sto m erg etd eta i II 

t> £§ http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p ea d d res sty p en o 

t> http ://www. i b m . e o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p ec o m p a ny d ata 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p eo ptc o m p a nyd ata 

t> http ://www. i b m . e o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p eo ptp ers o n a I d ata 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p eo ptp ers o n a I d ata n ew 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/jZca/sa p/s a p p ep ers o n a I d ata 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p ep ers o n a I d ata n ew 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p i c o m p a nyd ata 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/sa p p i com pa nyd atal7769l5436 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/sa p p i com pa nyd atax 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p i c o py ref eren c e 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p i o ptc ompa nyd ata 

t> http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 c a/s a p/s a p p i o ptc ompa nyd atal697663185 

t> fij http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 ca/sa p/s a p p i o ptc ompa nyd atax 

|> E§j http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j 2 ca/sa p/s a p p i o ptp ers o n a I d ata 

> EfJ http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 c a/s a p/s a p p i o ptp ers o n a I d atal514G735Q6 

> E§| http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 c a/s a p/s a p p i o ptp ers o n a I d atax 

> E§§ http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j 2 c a/s a p/s a p p i p ers o n a I d ata 

> Ejjj http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j 2 c a/s a p/s a p p i p ers o n a I d atal389GQ24G9 

> E§j http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j 2 c a/s a p/s a p p i p ers o n a I d atax 

> E§j http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j 2 ca/sa p/s a p retu rn 

> E§§ http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j2 c a/s a p/s a p retu rn2Q351Q914 

> Ejjj http ://www. i b m . c o m/xm I n s/p ro d/web s p h ere/j 2 c a/s a p/s a p retu rnG19G4789Q 
A g Flows 

pi SampleMsgFlow.msgflow 

> S 1 ESQLs 

j 10 Adapters 
a ^ Outbound 
a t* SAP 

SapCustomerOutbouncl.outaclapter 

> [J§! Flow Tests 

> lb Other Resources 

> ® BARs 

> (lJ Independent Resources 

Figure 5-20 Application schema definitions 

5.2.4 Broker configuration for SAP request nodes 

In this section, we modify the broker properties to refer to the correct location for the Jco Jars 
and native libraries at run time. 

Setting the path for SAP 

First, we use the mqsichangeproperties command to update the location of the JAR file 
(sapjco3.jar) and native library (sapjco3.dll) for the SAP adapter. 

1 . To use this command, open a command prompt and switch to the bin directory for 
WebSphere Message Broker, for example, C:\Program Files\IBM\MQSI\8.0.0.0\bin. 

2. Enter mqsi profi 1 e to prepare the environment for commands. 
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3. The following command is used to set the path for the JAR file: 

mqsi changeproperties BrokerName -c ElSProviders -o SAP -n jarsURL -v Jco loc 
In this scenario, we enter the following command: 

mqsi changeproperties SAMPLEBROKER -c ElSProviders -o SAP -n jarsURL -v 
C:\SAP_JC0 

4. The following command is used to set the path for the SAP native library: 

mqsi changeproperties BrokerName -c ElSProviders -o SAP -n nativeLibs-v Jco loc 
In this scenario, we enter the following command: 

mqsi changeproperties SAMPLEBROKER -c ElSProviders -o SAP -n nativeLibs -v 
C:\SAP_JC0 

UserlD and Password for adapter connection 

Associate the userlD and password values with the adapter component used by the SAP 
Request nodes: 

1 . Stop the broker: 

mqsi stop SAMPLEBROKER 

2. Set the user ID and password for the component. The command format is: 
mqsi setdbparms brokerName -n eis : :Adaptername -u userid -p password 
In this example, we enter: 

mqsi setdbparms SAMPLEBROKER -n ei s : :SapOutboundCustomer.outadapter -u MyUserlD 
-p MyPassword 

3. Restart the broker with the following command: 
mqi start SAMPLEBROKER 

5.2.5 Writing the code for the SAP nodes 

After the adapter connection is configured, you will find a number of schema definitions 
created by the SAPRequest node. These schemas provide the message model for the BAPI 
queries and are generated based on the entity descriptions with BAPI. You can change these 
element names and descriptions to be more meaningful and accessible. 


5.2.6 Coding the ESQL for the Compute nodes 

Compute nodes are used to process the errors and to add some data to update the SAP 
Customer record. 

Catch FlowErrors and CatchSAPErrors Compute nodes 

These nodes are used to capture errors during the flow and put them out as MQ messages. 
In this simple scenario, the same code will be used for both compute nodes: 

1 . Double-click the Catch FlowErrors node to open the ESQL. Replace the 
SampleFlow_Compute module with the code in Example 5-1 . 

Example 5- 1 ESQL for handling errors 

CREATE COMPUTE MODULE Sampl eMsgFl ow_Proc_Errors 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 
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CALL CopyMessageHeaders () ; 

-- Create an error message detailing the broker exception message 
SET OutputRoot.XMLNSC. Fai 1 ed= 1 Fai 1 ureData 1 ; 

SET OutputRoot.XMLNSC. Fai 1 ed. Body=InputBody ; 

SET OutputRoot.XMLNSC. Fai 1 ed. Except ion= Input Except i on Li st; 

-- CALL CopyEnti reMessage() ; 

RETURN TRUE; 

END; 

CREATE PROCEDURE CopyMessageHeaders () BEGIN 
DECLARE I INTEGER 1; 

DECLARE J INTEGER; 

SET J = CARD I NALI TY (Input Root .*[] ) ; 

WHILE I < J DO 

SET OutputRoot.*[I] = InputRoot.*[I] ; 

SET I = I + 1; 

END WHILE; 

END; 

CREATE PROCEDURE CopyEnti reMessage () BEGIN 
SET OutputRoot = InputRoot; 

END; 

END MODULE; 


2. Save and close the ESQL. 

3. In the Basic tab of the Properties view for both the CatchFlowErrors and CatchSAPErrors, 
change the ESQL module name to SampleMsgFlow_Proc_Errors. 

4. Save the message flow. 

AddCustDetail Compute node 

This node is used to construct a request message to update the customer information about 
the SAP system. In the SAP environment, SapBapiCustomerCreatefromdatal creates a 
customer record with the details of the referenced customer. This record can be updated later 
using SapBapiCustomrChangefromdatal : 

1 . Double-click the AddCustDetails node in the message flow to open the ESQL. 

2. Replace the default module generated with the code in Example 5-2. 

Example 5-2 Compute node example 
DECLARE ns3 NAMESPACE 

1 http: //www. i bm. com/xml ns/prod/websphere/j2ca/sap/sapbapi customercreatefromdata 
l 1 ; 

DECLARE ns5 NAMESPACE 

1 http: //www. i bm. com/xml ns/prod/websphere/j2ca/sap/sapbapi customerchangefromdata 
l 1 ; 

DECLARE ns8 NAMESPACE 

1 http: //www. i bm. com/xml ns/prod/websphere/j2ca/sap/sapbapi customergetdetai 11'; 

CREATE COMPUTE MODULE Sampl eMsgFl ow_AddCustDetai 1 s 

CREATE FUNCTION Main() RETURNS BOOLEAN 

BEGIN 

CALL CopyMessageHeaders () ; 

-- Copy the customerno into Environment tree. 
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CREATE NEXTSIBLING OF Envi ronment . Root TYPE NameValue NAME 1 Customerno 1 VALUE 
InputBody .ns3:SapBapi CustomerCreatefromdatal .Customerno; 

-- Copy the customerno into Output root. 

SET Output Root. XMLNSC.ns5:SapBapiCustomerChangefromdatal. Customerno = 
InputBody. ns3:SapBapi CustomerCreatefromdatal .Customerno; 

-- Create a reference for the values being updated 

DECLARE custref REFERENCE TO 0utputRoot.XMLNSC.ns5:SapBapiCustomerChangefromdatal; 

-- Update the values 

SET custref. PiDistrChan = '01'; 

SET custref. Pi Division = '01'; 

SET custref .PiSalesorg = '0001'; 

SET custref . SapPi Personaldata. Fi rstname = 'Jane 1 ; 

SET custref. SapPi Personal datax. Fi rstname = 'X 1 ; 

SET custref .SapPi Personaldata. Lastname = 'Doe 1 ; 

SET custref .SapPi Personal datax. Lastname = 'X'; 

SET custref .SapPi Personaldata. Ci ty = 'Carlisle'; 

SET custref .SapPi Personal datax. City = 'X'; 

SET custref .SapPi Personaldata. PostlCodl ='94010'; 

SET custref .SapPi Personal datax. PostlCodl = 'X'; 

SET custref .SapPi Personaldata. EMai 1 = 'john@john.com'; 

SET custref .SapPi Personal datax. EMai 1 = 'X'; 

SET custref .SapPi Personal datax. Tel INumbr = '999-999-9999'; 

SET custref .SapPi Personaldata. Country = 'US'; 

SET custref .SapPi Personal datax. Country = 'X'; 

SET custref .SapPi Personaldata. Region = ' CA ' ; 

SET custref .SapPi Personal datax. Region = 'X'; 

SET custref .SapPi Personaldata. LanguP = ' EN ' ; 

SET custref .SapPi Personal datax. LanguP = 'X'; 

SET custref .SapPi Personaldata. Currency = 'USD'; 

SET custref .SapPi Personal datax. Currency = 'X'; 

-- CALL CopyEntireMessage() ; 

RETURN TRUE; 

END; 

CREATE PROCEDURE CopyMessageHeaders () BEGIN 
DECLARE I INTEGER 1; 

DECLARE J INTEGER; 

SET J = CARD I NALITY (Input Root .*[] ) ; 

WHILE I < J DO 

SET OutputRoot .*[1] = InputRoot .*[1] ; 

SET I = I + 1; 

END WHILE; 

END; 

CREATE PROCEDURE CopyEnti reMessageQ BEGIN 
SET OutputRoot = InputRoot; 

END; 

END MODULE; 


3. Save and close the ESQL. 

4. In the Basic tab of the Properties view for the AddCustDetails node, change the ESQL 
module name to Sampl eMsgFl ow_AddCustDetai 1 s. 

5. Save the message flow. 
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5.2.7 Coding the Filter Request .NETCompute node 

Use the following steps to write this code: 

1 . Open the solution for MBCreateCRMOnline in Visual Studio. 

2. In the Solution Explorer, double-click Fi 1 terRequest . cs to open it. 

3. Replace the Evaluate() method with the code shown in Example 5-3. 

Example 5-3 .NETCompute node filter request 

public override void Eval uate(NBMessageAssembly i nputAssembly) 

{ 

//Make connection to output terminals 
NBOutputTerminal outSAPRetrieve = OutputTerminal ("Out") ; 
NBOutputTerminal outSAPCreate = OutputTerminal ("altOut") ; 
NBOutputTerminal fai 1 ureTermi nal = OutputTerminal ("Failure") ; 

NBMessage inputMessage = i nputAssembly .Message; 

NBElement root = i nputMessage. RootEl ement ; 
try 
{ 

NBElement tls = root; 

NBElement key = root[NBParsers.XMLNSC.ParserName] . Fi rstChi 1 d ; 

// Add user code in this region to filter the message 
switch (key. Name) 

{ 

case "SapBapiCustomerGetdetail 1": 

// Existing Customer. 

// Extract details from SAP, create an account into CRM. 
i nputAssembly . Envi ronment. RootEl ement .Add Las tChi 1 d (key) ; 
outSAPRetrieve. Propagate (i nputAssembly) ; 
break; 

case "SapBapiCustomerCreatefromdatal" : 

// New customer. Create record in SAP and CRM. 
i nputAssembly . Envi ronment . RootEl ement .Add Las tChi 1 d(key) ; 
outSAPCreate. Propagate(i nputAssembly) ; 
break; 

default: 

//Unrecognized flow. Move it to Failure, 
fai 1 ureTermi nal . Propagate(i nputAssembly) ; 
break; 

} 

} 

catch (Exception) 

{ 

fai 1 ureTermi nal . Propagate(i nputAssembly) ; 

} 

} 


The Evaluate method is invoked by DataFlowEngine when there is a message in the 
Flowlnput node. 
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In the Evaluate method, we check the first child of the XML message: 

► If it is “SapBapi CustomerGetdetai 1 1”, we assume it is an existing customer and route it to 
SAPRetrieve node. 

► If it is “SapBapi CustomerCreatefromdatal”, we assume it is a new customer and route it 
SAPCreate. 

We add the incoming message to the Environment as the last child to retrieve the original 
message again later in the message flow. 

5.2.8 Writing the code for the database operations 

The DB<->CreateCRMOnlineCustomer node contains a lot of activity, including database 
operations, Microsoft Dynamics CRM operations, and code related to the broker. We 
categorize this sections for each activity. 

We start by adding a new application configuration file (App.Config) to the 
MBCreateCRMOnline project in Visual Studio: 

1 . In the Solution Explorer, right-click the project, and select Add New Item. 

2. Select Visual C# Items in the Installed Templates column, and select Application 
Configuration File. 

3. Leave the name as App.config, and click Add. 

4. The App.config file is used to store the credentials and URIs and any volatile data that can 
be accessed from it during application execution. Replace the generated XML in 
App.config with the XML in Example 5-4. 

Example 5-4 Contents of app. con fig 

<?xml version="1.0" encodi ng="utf-8" ?> 

<configuration> 

<appSettings> 

<cl ear/> 

<add key= l, DBConnectionString M val ue="Server=ITSOSQLServer; 

Database=ITSOCRM; 
user id=Myllser; 
password =MyPw; 

Trusted_Connection = no; 
connection timeout = 60;" /> 

<add key = l, StoredProcedureName M value = "dbo.GetAccNumberByEmai 1 11 /> 

<add key ^'CRMURI" val ue="https://myid. crm. dynamics. com"/> 

<add key = l, CRMUser M value = ll MyUser" /> 

<add key = M CRMUserPwd" val ue="MyPW l 7 > 

</appSetti ngs> 

</configuration> 

5. Save and close App.config. 

Code for interactions with the database 

Add a new class to the project called DBOperations. We use this class to manage all 
database- related operations. To add the DBOperations class to the project: 

1 . Add a new reference to the project. Right-click References in the Solution Explorer, and 
select Add Reference. Click the .NET tab, select System.Configuration, and click OK. 
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2. Select Project Add Class. 

3. Select Class, enter DBOperati ons . cs as the name, and click Add. 

4. Replace the generated code with the code shown in Example 5-5. 

Example 5-5 Code for DBOperations 

using System; 

using System. Col lections; 

using System. Li nq; 

using System. Text; 

using System. Data. SqlCl ient; 

using System. Configuration; 

namespace MBCreateCRMOnl ine 

{ 

/// <summary> 

III Performs all the Database related operations. 

Ill Its major function is to access a stored procedure 
III in Database and get AccountNumber. 

Ill </summary> 
internal class DBOperations 
{ 

SqlConnection dbConnection = null; 

String connString = null; 

String procedureName = null; 

Sql Command query; 

III <summary> 

III Constructor. Opens the Database connection. 

Ill </summary> 
public DBOperati ons () 

{ 

if (ConfigurationManager.AppSettings. Count > 0) 

{ 

connString = 

(Stri ng) Conf i gurati onManager . AppSetti ngs ["DBConnecti onStri ng "] ; 
procedureName = 

(Stri ng)Confi gurati onManager. AppSetti ngs ["StoredProcedureName"] ; 

} 

//Open Database. 

dbConnection = new SqlConnection(connString) ; 
dbConnection. 0pen() ; 

} 

III <summary> 

III Check Database Record and return Account number. 

Ill </summary> 

III <param name="emai 1 "></param> 

III <returns></returns> 

internal String CheckDBRecordsFromSAP(Stri ng email) 

{ 

Stri ng accNo = null; 
try 
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{ 

//Create a new isntance of sql command. 

query = new Sql Command (procedureName, dbConnection) ; 

query. CommandType = System. Data. CommandType.StoredProcedure; 

//Input parameter. 

Sql Parameter email_ = new Sql Parameter ("Qemai 1 11 , 

System. Data. Sql DbType. VarChar, 240) ; 

emai 1_. Val ue = emai 1 ; 

//Output parameter. 

SqlParameter accNum = new Sql Parameter ("@AccNo" , System. Data. SqlDbType. VarChar, 
15); 

accNum. Direction = System. Data. ParameterDi recti on. Output; 

query . Parameters .Add (emai 1_) ; 
query . Parameters .Add (accNum) ; 

//Execute. 

query. ExecuteNonQuery () ; 

//Grab the reutrn value, 
if (accNum. Val ue != null) 

accNo = accNum. Value. ToStringO ; 

//Release the query resources, 
query .Di spose() ; 


} 

catch (Exception) 

{ 

throw; 

} 

return accNo; 

} 

} 

} 


This code queries the database and checks to see if a customer with the given email address 
already exists. If the customer exists, it retrieves the account identifier and tags it on to the 
CRM account. 

The code uses a stored procedure on the SQL Server to return the Customer Account 
Number. The stored procedure takes one String type input parameter Email and returns the 
String type AccountNumber, shown in Example 5-6 on page 135. 

Create the following stored procedure for the SQL database instance that the message flow is 
using. Stored procedures can be added from Visual Studio in the Server Explorer view. 
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Example 5-6 SQL server database query 


CREATE PROCEDURE GeAccNumberByEmai 1 (OEmail NVARCHAR(50) ,@AccNo NVARCHAR(15) 
OUTPUT) 

AS 

Select @AccNo = AccountNumber from dbo. Accounts where CustomerlD IN(Select 
CustomerlD from dbo. Customers where Emai 1 Address=@Emai 1 ) 

GO 


5.2.9 Writing the code for accessing Microsoft Dynamics CRM Online 

Microsoft Dynamics CRM offers an early-bound entity data model, late-bound entity data 
model, REST endpoints, and WSDL interfaces for client connectivity. Programming scenarios 
in earlier versions of Microsoft Dynamics CRM were based on WSDL with early-bound 
classes for each entity and a DynamicEntity class for late-bound programming scenarios. 
Microsoft Dynamics CRM 201 1 no longer uses WSDL but now provides assemblies to 
reference and connect to Microsoft Dynamics CRM 201 1 for both early-bound and late-bound 
programming scenarios. 

In Microsoft Dynamics CRM, entities are used to model and manage business data. For 
example, entities, such as account and contact, can be used to track and support customer 
activities. Each entity has an array of attributes of a particular data type. For example, account 
and contact are entities to model customer data and contain attributes that define such things 
as Name, Email, Phone, and so on. 

► Late-bound 

This programming models allows applications to access the entities that are not yet 
defined and allows code to be written in a generic manner. The code can contain and 
define custom entities and their attributes that are not available during code compilation. 
When initialized, the Entity class must have a logical name (to represent an entity, such as 
contact or account) and a property context of the entity’s attributes. 

► Early-bound 

The Microsoft Dynamics CRM code generation tool (CrmSvcUtil) creates early-bound 
entity classes that are used to access the business data. These classes include one class 
for each entity in your installation, including custom entities. Any time customizations are 
made to the system, these classes must be regenerated. Classes created by the code 
generation tool include all entity attribute and relationships. 

Other programming models are: 

► REST endpoint for AJAX and Silverlight clients to access Microsoft Dynamics CRM 
directly rather than invoking a SOAP-based web service. 

► WSDL for the use by non .NET applications and does not depend on using Dynamics 
CRM assemblies. 

More information about these programming models are at: 
http://msdn.mi crosoft .com/en-us/1 i brary/gg327971.aspx 
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Programming model for the scenario: This scenario demonstrates interactions with 
Microsoft Dynamics CRM Online using the late-bound programming model. 


You can also use the early-bound programming model. In that case, the corresponding 
managed code must be generated using the CrmSvcUtil tool and must be added and 
referenced by the CreateCrmCustomer.es class. You must create the 
Customer(Account, Entity) data using the syntax and semantics of the early-bound 
programming model. 

Using web services 

Microsoft Dynamics CRM provides two web services for accessing CRM Online, one to 
identify your organization and another to access the CRM data. 

IDiscoveryService web service 

A single Microsoft Dynamics CRM installation can host multiple organizations on multiple 
servers. Therefore, it is important to specify which organization you want to access. The 
IDiscoveryService web service returns a list of organizations that the specified user belongs 
to and the URL endpoint address for each organization. The service only returns those 
organizations to which a user has access. For more information about the IDiscoveryService 
web service, see: 

http://msdn.mi crosoft .com/en-us/1 i brary/gg328127.aspx 

lOrganizationService web service 

The lOrganzationService primary web service is for accessing data and metadata in 
Microsoft Dynamics CRM 201 1 . For more information about lOrganization web service, see: 

http://msdn.mi crosoft .com/en-us/1 i brary/gg309449.aspx 

Add Microsoft assemblies to your project 

Using Microsoft Dynamics CRM SDK assemblies to access the CRM data is the 
recommended developer scenario for Dynamics CRM 201 1 and Online. These assemblies 
are in the SDK\Bi n folder of the Microsoft Dynamics CRM SDK along with XML Intellisense 
files for Visual Studio. For more information about the assemblies, their contents, and usage, 
see: 

http://msdn.microsoft.eom/en-us/l ibrary/gg334621.aspx 

Authenticate users with Microsoft Dynamics CRM web services 

Microsoft Dynamics CRM supports multiple authentication models. The type of authentication 
interface that is used depends on the type of deployment your application is accessing, 
Microsoft Dynamics CRM Online or Microsoft Dynamics CRM 2011. Microsoft CRM 
Online-based deployment supports two security models: Claim-based authentication and 
Active Directory authentication. 

Authentication is performed with the help of proxy classes. This scenario uses the 
OrganizationServiceProxy and DiscoveryServiceProxy classes for authenticating with CRM 
Online. The four-parameter constructor of these classes supports Microsoft Dynamics CRM 
Online Windows Live ID deployments. These proxy classes automatically handle Claims or 
Active Directory authentication for the user. More information about this can be found at: 

http://msdn.mi crosoft .com/en-us/1 i brary/gg334502.aspx 

Getting started accessing CRM data 

This section provides a summary of the steps you need to follow to access CRM data. 
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Before creating your code, make sure you meet the following prerequisites: 

► Make sure you have access to a Microsoft Dynamics CRM server, and note the server 
name. 

► If you are accessing Microsoft Dynamics CRM Online, install Windows Identity 
Foundation. 

► Have your Windows Live ID, userlD, and password available. 

To get started: 

1 . Create a New Project, or open your existing project in Visual Studio. 

2. Add references in your project for Microsoft Dynamics CRM assemblies (recommended 
approach). 

3. Create an App.Config file with entries to contain the CRM server name, Live ID, and 
password. 

4. Create an instance of the DiscoveryService and access the list of Organizations you are 
authorized to access. 

5. Create an instance of OrganizationService to access specific a Organization on CRM to 
create, update, retrieve, and delete the data. 

Example 

Use the following procedure to practice accessing CRM data. Note that we use the 
late-bound programming model: 

1 . Access Microsoft Dynamics CRM Online and obtain the server name (for example, 

https : / /id. crm5 . dynami cs . com) . 

2. Use your Live ID for CRM Online authentication. 

3. Open the MBCreateCRMOnline solution in Visual Studio. 

4. Add the references highlighted in Figure 5-21 to Project references. 

The System, references can be found in the .NET tab. However, the 
microsoft.crm.sdk.proxy and microsoft.xrm.sdk references are found by using the Browse 
tab to locate the following dll files in the Microsoft CRM SDK installation: 

- Microsoft.Crm.Sdk.Proxy: sd/c_/'nsfa/Asdk\bin\microsoft.crm.sdk.proxy.dll 

- Microsoft.Xrm.Sdk: sdk_/'nsfa/Asdk\bin\microsoft.xrm.sdk.dll 



Figure 5-21 CRM libraries 
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5. While authenticating, you must register a computing device with Windows Live ID through 
the generation of a Device ID and password. There is a helper class deviceidmanager.es 
available in the sdk_instal Z\sdk\sampl ecode\cs\hel percode to do this job. 

You can add this class to your project or write your own code for doing this job. In our 
scenario, we use the helper class for device registration. 

Add the deviceidmanager.es class to MBCreateCRMOnline: 

a. Right-click the project in the Solution Explorer, and select Add Existing Item. 

b. Browse for the helper class deviceidmanager.es in 
sc//c_/nsfa//lsdk\samplecode\cs\helpercode. Select it, and click Add. 

6. Create a new class CreateCrmCustomer.es: 

a. Right-click the project in the SolutionExplorer, and select Add Class. Name the 
class CreateCrmCustorner.es, and click Add. 

b. Replace the using statements at the top of the file with those shown in Example 5-7. 

Example 5-7 Using statements for 
using System; 

using System. Servi ceModel ; 

using System. Servi ceModel .Description; 

using System. Reflection; 

using System. Col lections; 

using System. Configuration; 

using IBM. Broker. Plugin; 

// These namespaces are found in the Microsoft.Xrm.Sdk.dll assembly 

// located in the SDK\bin folder of the SDK download. 

using Microsoft. Xrm.Sdk; 

using Microsoft. Xrm.Sdk. Query; 

using Microsoft. Xrm.Sdk. Cl ient; 

usi ng Mi crosoft .Xrm.Sdk. Di scovery; 

usi ng Mi crosoft .Crm. Sdk. Messages; 

usi ng Mi crosoft .Crm. Servi ces.Uti 1 i ty; 


c. Create code for the following actions: 

• Access the user/userid/password values for CRM Online from the App.Config file. 

• Create an instance of IDiscoverService. 

• Authenticate on IDiscoveryService. 

• Retrieve the list of organizations you are authorized to access. 

• Create an Instance of lOrganizationService. 

• Create a Customer(Account, Contact) on CRM Online. 

Example 5-8 shows the code snippet that performs these actions. Replace the generated 
code for the CreateCrmCustomer class with the code in Example 5-8. 

Example 5-8 CRM Online code snippet 
III <summary> 

III Demonstrates connectivity to Microsoft Dynamics CRM Online. 

Ill Action to Create a Microsoft Dynamics CRM Online record. 

Ill </summary> 

internal class CreateCrmCustomer 

{ 

//Key fields to access Microsoft Dynamics CRM Online, 
private String _server = "OrganizationllniqueName"; 
private String _userName = "username@mydomain.com"; 
private String _password = "password"; 
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//Setter and Getters 

private OrganizationDetail currentOrgani zationDetai 1 { get; set; } 
private IDi scoveryService DisService { get; set; } 
private IOrganizationService OrgService { get; set; } 
private Cl ientCredenti al s cl ientCredential s { get; set; } 
private Cl ientCredenti al s deviceCredenti al s { get; set; } 
private bool I s Li velDAuthType { get; set; } 

/// <summary> 

III Class Constructor 

III Looks up for uri,uid and pwd from App.Config 
III Creates IDi scoveryServi ce proxy 
III Authenticates 

III Create proxy instance of IOrganization Context. 

Ill </ summary > 

public CreateCrmCustomer() 

{ 

if (ConfigurationManager.AppSettings. Count > 0) 

{ 

_server = (String)ConfigurationManager.AppSetti ngs ["CRMURI "] ; 

_userName = (String)ConfigurationManager.AppSettings[ M CRMUser M ] ; 

_password = (String)ConfigurationManager.AppSettings["CRMUserPwd"] ; 

} 

Uri discoveryllri = GetDi scoveryServi cellri (_server) ; 

//Create IDi scoveryServi ce instance. 

IServiceConfiguration<IDi scoveryServi ce> dinfo = 

Servi ceConfi gurati onFactory .CreateConfi gurati on<IDi scoveryServi ce>(di scoveryllri ) ; 
cl ientCredential s = new ClientCredentialsQ ; 

Di scoveryServi ceProxy disSrvProxy = null; 

if (GetServerAuthenticationType(di scoveryllri) == AuthenticationProviderType.Liveld) 

{ 

cl ientCredential s.UserName.UserName = _userName; 
cl ientCredential s.UserName. Password = _password; 
devi ceCredenti al s = Devi celdManager. LoadOrRegi sterDevi ce() ; 
disSrvProxy = new Di scoveryServi ceProxy (di scoveryllri 9 null, cl ientCredenti als, deviceCredenti al s) ; 

I s Li velDAuthType = true; 

} 

//Authenti cate, 
di sSrvProxy .Authenti cate() ; 

RetrieveOrganizationsRequest orgRequest = new RetrieveOrganizationsRequestQ ; 
RetrieveOrganizationsResponse orgResponse = di sSrvProxy. Execute(orgRequest) as 
Retri eveOrgani zati onsResponse; 

//Create IOrganizationService instance. 
currentOrgani zati onDetai 1 = orgResponse. Detai 1 s [0] ; 

Uri orgServiceUri = new Uri (currentOrgani zati onDetai 1 .Endpoints [EndpointType.Organi zati onService]) ; 
if (IsLi velDAuthType) 

{ 

OrgService = new Organi zati onServi ceProxy (orgServi ceUri 9 null, cl ientCredenti al s, 
devi ceCredenti al s) ; 

} 

el se 


IServi ceConfi gurati on<I0rgani zati onServi ce> orgConf i glnfo = 

Servi ceConfi gurati onFactory . CreateConfi gurati on<I0rgani zati onServi ce>(orgServi ceUri ) ; 
OrgService = new Organi zati onServi ceProxy (orgConfi glnfo, cl ientCredenti als) ; 
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/// <summary> 

III From the Server provided in App.Config. Construct a meaningful 
III URI for Di scoveryServi ce. 

Ill </ summary > 

III <param name="serverName"></param> 

III <returns></returns> 

public Uri GetDi scoveryServi cellri (stri ng serverName) 

{ 

string uri Suffix = @ M /XRMServi ces/2011/Di scovery . svc" ; 
return new Uri (string. Format (" {0} { 1} 11 , serverName, uriSuffix)); 

} 

III <summary> 

III Authneti cation Type for this Deployment. 

Ill </ summary > 

III <param name="uri "></param> 

III <returns></returns> 

public AuthenticationProviderType GetServerAuthenti cationType(Uri uri) 

{ 

return Servi ceConf i gurati onFactory .CreateConf i gurati on<IDi scoveryServi ce>(uri ) . Authenti cati onType 

} 


III <summary> 

III Creates a Crm Customer(account, contact) . 

Ill Makes the contact as the primary contact of the account. 

Ill </ summary > 

III <param name="input">Li st of attri butes (xml form)</param> 

III <param name =,l custNumber M >val ue from SAP Records</param> 

III <returns></returns> 

internal Guid CreateCrmCustomerRel ation(NBEl ement input. String custNumber) 

{ 

Entity contact = new Enti ty ("contact") ; 

Entity account = new Enti ty ("account") ; 
if (input != null) 

{ 

contact [" f i rstname"] = input . Fi rstChi 1 d.Val ueAsString; 

NBE1 ement sibling = i nput . Fi rstChi 1 d .NextSi bl i ng; 
while (sibling != null) 


swi tch (si bl i ng.Name.Tol_ower() ) 

{ 

case "lastname" : 

if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact ["1 astname"] = sibling. Val ueAsString; 

} 

break; 

case "jobtitle": 

if (!sibl ing.Val uelsNul 1 ) 

{ 

contact ["jobtitle"] = sibl ing.Val ueAsString; 

} 

break; 

case "street": 

if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact ["addressl_l inel"] = si bl ing.Val ueAsString; 
account ["addressl_l inel"] = si bl ing.Val ueAsString; 

} 

break; 

case "city": 
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if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact [ M addressl_ci ty "] = si bl ing.Val ueAsString; 
account [ M addressl_ci ty "] = si bl ing.Val ueAsString; 

} 

break; 

case "regionstateprovincecounty" : 
if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact [ M addressl_county M ] = s i bl ing.Val ueAsString; 
account [ M addressl_county M ] = s i bl ing.Val ueAsString; 

} 

break; 

case "countrykey" : 

if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact [ M addressl_country M ] = si bl ing.Val ueAsString; 
account [ M addressl_country M ] = si bl ing.Val ueAsString; 

} 

break; 

case "ci typostal code" : 

if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact [ M addressl_postal code"] = sibl ing.Val ueAsString; 
account [ M addressl_postal code"] = sibl ing.Val ueAsString; 

} 

break; 

case "emai 1 address" : 

if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact ["emai laddressl"] = sibling. Val ueAsString; 
account ["emai 1 addressl 11 ] = sibling. Val ueAsString; 

} 

break; 

case "tel 1 number" : 

if ( !sibl ing.Val uelsNul 1 ) 

{ 

contact ["tel ephonel"] = sibl ing.Val ueAsStri ng; 
account ["tel ephonel"] = sibl ing.Val ueAsStri ng; 

} 

break; 
defaul t : 
break; 

} 

sibling = si bl ing.NextSibl ing; 

} 

} 

//Create a Contact firts. 

Guid contactid = OrgService.Create(contact) ; 

//Instantiate Account. 

account ["name"] = "SAP Customer"; 

account ["accountnumber"] = custNumber; 

//Associate Account and contact as primary contact. 

account .Attri butes .Add("primarycontactid" , new Enti tyReference("contact" , contacti d)) ; 
//Create account. 

return OrgServi ce.Create(account) ; 
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d. Save CreateCrmCustomer.es. 


5.2.10 Writing the code for the .NETCompute node (Create) - 
DB<->CreateCRMOnlineCustomer 

Write the code for the DB<->CreateCRMOnlineCustomer node for calling the methods on 
DBOperations or CreateCrmCustomer.es classes: 

1 . In Visual Studio, open the CreateCrmOnline.es class. 

2. Add the code in bold shown in Example 5-9 to the class. 

Example 5-9 Code to add to the class 

namespace MBCreateCRMOnline 

{ 

/// <summa ry> 

III CreateCrmOnl i ne Class 
III </summary> 

public class CreateCrmOnl i ne : NBComputeNode 

{ 

CreateCrmCustomer crmOrg = new CreateCrmCustomer() ; 

DBOperations dbOp = new DBOperations () ; 


3. Replace the Evaluate() method with the code in Example 5-10. 

Example 5-10 DB<->CreateCRMOnlineCustomer code snippet 

public override void Eval uate(NBMessageAssembly i nputAssembly) 

{ 

//Create output connections 

NBOutputTerminal outTerminal = OutputTermi nal ("Out") ; 

NBOutputTerminal fai 1 ureTermi nal = OutputTermi nal ("failure") ; 

NBMessage inputMessage = i nputAssembly. Message; 

// Create a new empty message, ensuring it is disposed after use 
using (NBMessage outputMessage = new NBMessageQ) 

{ 

NBMessageAssembly outAssembly = new NBMessageAssembly (i nputAssembly, outputMessage); 
NBElement inputRoot = inputMessage. RootElement; 

NBElement outputRoot = outputMessage. RootElement; 
try 
{ 

// Optionally copy message headers, remove if not needed 
CopyMessageHeaders (i nputRoot , outputRoot) ; 

#region UserCode 

NBElement envRoot = i nputAssembly . Envi ronment. RootEl ement; 

NBElement key = envRoot . Fi rstChi 1 d; 
string notargetnamespace = "" ; 
string namespaceStore = 

"http: //www. i bm. com/xml ns/prod/websphere/j2ca/sap/sapbapi customergetdetai 11"; 

Guid response = new Guid(); 

if (key. Name. ToLower() . Start sWith("sapbapi customergetdetai 11")) 
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{ 

NBElement Action = inputRoot[notargetnamespace, "DataObject"] [namespaceStore, 
"SapBapiCustomerGetdetai 11"]; 

NBElement data = Action["SapPePersonaldataNew"] ; 

NBElement sapid = key. Fi rstChi 1 d; 

response = CreateCrmCustomer(data, sapid. ValueAsString) ; 

} 

el se i f (key .Name. ToLower() . Start sWi th ("sapbapi customercreatefromdatal") ) 

{ 

NBElement custdet = key . Fi rstChi 1 d; 

NBElement sapid = envRoot . LastChi 1 d; 

response = CreateCrmCustomer(custdet, sapid. ValueAsString) ; 

} 

//construct the output message. 

outputRoot. Create LastChi 1 dlls i ngNewParser(NBParsers .XMLNSC. ParserName) ; 
outputRoot ["XMLNSC"] .CreateFi rstChi 1 d(nul 1 , "CrmOnl ineCustomer") ; 
outputRoot ["XMLNSC"] ["CrmOnl i neCustomer"] .CreateFi rstChi 1 d(nul 1 , 

"Acti vi tyld") .SetVal ue (response. ToByteArray ()) ; 

#endregion UserCode 

// Send the message to output terminal. 
outTerminal . Propagate(outAssembly) ; 

} 

catch (Exception e) 

{ 

//Create and construct an exception message 

outputRoot .CreateLastChi 1 dllsi ngNewParser(NBParsers .XMLNSC. ParserName) ; 
outputRoot ["XMLNSC"] .CreateFi rstChi 1 d (nul 1 , "CrmOnl i neCustomer") ; 
outputRoot ["XMLNSC"] ["CrmOnl i neCustomer"] . CreateFi rstChi 1 d (nul 1 , 

" Except ionDetai Is") .SetVal ue(e.ToStri ng() ) ; 

//Put it to Fai 1 ureTermi nal 
failureTerminal . Propagate(outAssembly) ; 

} 

} 

} 


4. Example 5-1 1 contains the code for adding a method to invoke database and CRM Online 
operations. Add the following code below the Evaluate method (added in Example 5-10 on 
page 142). 

Example 5-11 Database and CRM Online operations method 
III <summary> 

III Creates a CRM Online Customer(Account, Contact) 

III </summary> 

III <param name="entityAttributes"></param> 

III <param name="custno"></param> 

III <returns></returns> 

private Guid CreateCrmCustomer(NBEl ement entityAttributes, String custno) 

{ 

//Check if customer exist in Database. 

String dbCustAcc = 

dbOp.CheckDBRecordsFromSAP(enti tyAttri butes ["EMai 1 "] . Val ueAsStri ng) ; 
if (dbCustAcc != null && dbCustAcc. Length > 0) 

{ 
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custno = custno + "_DB" + custno; 

} 

//Create CrmOnline customer. 

return crmOrg.CreateCrmCustomerRel at i on (enti tyAttri butes , custno) ; 


5. Save all files by pressing Ctrl+Shift+S, and build the project by selecting Build Build 
Solution. 


5.3 Deploying the message flow 

Deployment is the process of transferring data to an execution group on a broker so that it can 
take effect in the broker domain. Message flows and associated resources are packaged in 
broker archive (BAR) files for deployment. 

Creating a broker archive (BAR) file 

To create a BAR file: 

1 . In the Message Broker Toolkit, select File New Message Broker Archive. 

2. Enter the name of your server project, or select one from the displayed list. The list is 
filtered to only show projects in the active working set. Enter a name for the BAR file that 
you are creating, as shown in Figure 5-22. Click Finish. 



Figure 5-22 Create a new BAR file 

3. A file with a .bar extension is created and is displayed in the Broker Administration 
Navigator view under the Broker Archives folder. See Figure 5-23 on page 145. 
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Figure 5-23 New BAR file 


4. Double-click the SampleFlow.bar file, and in the Content view, select the check box for 
the Sample application, as shown in Figure 5-24. Click Build and Save to add the BAR 
file. 


Prepare 

Select deployable resources to include in the broker archive 


Deployable Resources 

Select an application to package all its contained resources. Resources within an application are isolated from other 
applications. 

© Applications O Message flows, libraries and other message flow dependencies 
Text filter: ) type filter text 


Applications 


El St 

A- 0 g Sample 


Build and Save... 


Figure 5-24 Select deployable resources 


5. Save and close the bar file. 

Deploying the message flow 

To deploy the message flow. 

1 . Right-click the SampleFlow.bar file, and select Deploy, as shown in Figure 5-25 on 
page 1 46. 
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Figure 5-25 Deploy the BAR file 


2. Select the broker and execution group to where the BAR is to be deployed. In our 
scenario, we selected the default, as shown in Figure 5-26. Click Finish. 



Figure 5-26 Select the execution group for the BAR file 
When the deployment is complete, the flow is running, and you can test the flow. 
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5.4 Testing the message flow 


We will create a test client to verify that the message flow is showing the expected behavior 
and that it is creating a CRM Online customer either by retrieving data from SAP or from user 
input. 

Our scenario demonstrates two options: 

► A graphical user interface application designed using Windows Forms that can collect the 
user input and triggers the message flow by putting the user details as a WebSphere MQ 
message onto the Flowlnput node. 

► Alternatively you can test the message by simple adding a Flow test project on the 
Message Broker Toolkit. This can only serve as a unit-testing facility and is not scalable. 

The first option is recommended for a scalable and full-length application for triggering 
message flows and consuming message flow outputs. 


5.4.1 Windows Forms Project: GUI Based 

In this section, we build a front end GUI for customers who want to subscribe for a service on 
the Online stores website. The GUI is built using a Visual C# Windows Forms Application 
project. 

Creating a new Visual Studio project 

Open Visual Studio and use the following procedure to create a new project: 

1 . Select File New -» Project: 

a. In the Recent Templates column, select Visual C#, and in the list of templates, select 

Windows Forms Application. 

b. In the Name field, enter Subscri beToServi ce, and click OK. The new form will open for 
edit. 

2. In the Solution Explorer, right-click Forml.cs, and select Rename. Enter 
SubscribeToService.es as the new name. 

3. Use the Visual Studio Designer to create this form. You can access the Designer by 
selecting the SubscribeToService.es file in the Solution Explorer, and clicking the View 
Designer button. 

Use the Toolbox palette on the left side of the screen to add elements to the Form. If you 
do not see the Toolbox, select View -> Toolbox. 

The form has two tabs, as shown in Figure 5-27 on page 148. 
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Figure 5-27 Form tabs 


This step adds the tabs to the form: 

a. In the Toolbox, expand the Containers section, and drag TabControl to the form. Size 
the new box appropriately. 

b. Open the Windows Form Properties (View Properties Window). From the Control's 
(topmost) drop-down list, select tabControll. 

c. Select the TabPages property in the Behavior section, and click the (Collection) input 
button as shown in Figure 5-28. 


Properties 

tabControl 1 System . Windows . Forms . T abControl 


!l! zl \m\f 


ShowToolTips 

SizeMode 

Tablndex 


False 

Normal 

0 


TabStop 

Visible 

S 


(Collection) 

True 

True 


Figure 5-28 TabPages property 
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d. This will open the Collection Editor. Select tabPagel , and change the following 
properties, as shown in Figure 5-29: 



Figure 5-29 Collection Editor 

• In the Appearance section, find the Text property, and enter Have an account as the 
value. 

• In the Design section, find the (Name) property, and enter tbCustomerExi st as the 
value. 

e. Select tabPage2, and change the (Name) property value to tbNewCustomer and the 
value for the Text property to Create Account. 

f. Click OK. 

4. Build the Have an account tab. Select the tab on the form, and drag-and-drop the 
necessary control objects into the appropriate locations to create the Label and Text box 
for the Have an account tab, as shown in Figure 5-27 on page 148. 

Perform the following steps to create the form: 

a. Expand the Common Controls section in the Toolbox, and drag a Label and a Textbox 
to the top of the form to allow the user to input the customer account number: 

• Enter Customer Number* as the text for the label. 

• Enter txtCustNo as the (Name) property for the textbox 

The visible attributes of the control objects are set in the properties pane of Visual 
Studio, including the names of the objects. If the properties pane is not open and 
visible, select one of the control objects, and right-click to choose Properties. 

b. Add a button to the form, and use the Properties view to set the following properties: 

• Text: Subscribe 

• (Name): btnExi stCustSub 

c. Add a second button to the form, and use the Properties view to set the following 
properties: 

• Text: Clear 

• (Name): btnExi stCustCl ear 
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5. Build the Create Account tab. Select the tab on the form, and drag-and-drop the 

necessary control objects into the appropriate locations to create the Label and Text box 
for the tab, as shown in Figure 5-30. 



Figure 5-30 New customer sign in panel 

Perform the following steps to create the elements of the tab: 

a. Add a Label and a Textbox at the top of the form for each of the input fields shown in 
Figure 5-30, and set the (Name) property for each text box, as shown in the following 
list. 

Table 5-4 Textbox labels and Name properties 


Label 

Textbox (Name) property 

Title 

cbtitle 

FirstName 

tbNewCustFName 

LastName 

tbNewCustLName 

Email 

tbNewCustEmail 

Phone 

tbNewCustPh 

Addressl 

tbNewCustAddrl 

Address2 

tbNewCustAddr2 

City 

tbNewCustCity 

State 

tbNewCustSt 

Country 

tbNewCustCountry 
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Label 

Textbox (Name) property 

PostalCode 

tbNewCustZip 


b. Add a button to the form, and use the Properties view to set the following properties: 

• Text: Subscribe 

• (Name): btnNewCustSubscribe 

c. Add a second button to the form, and use the Properties view to set the following 
properties: 

• Text: Clear 

• (Name): btnNewCustCl ear 
Save the design. 


5.4.2 Writing the code for the SubscribeToService form 

This application uses WebSphere MQ .NET classes to create an MQ message that carries 
the customer information (customer number or personal information) as an XML message in 
the XMLNSC format to the Flowlnput queue. 

After the application places the message on the input queue, it polls the output queue for the 
output message. When the message flow completes execution, it places an MQ message on 
the queue with the CRM customer record identifier as the activityid. The application will pick 
up this message and display a message box to show the activityid that can be used to trace 
the current interaction. 

The WebSphere MQ connection parameter resource names can be provided using an 
App.Config file, and the WebSphere MQ operation will be performed in a new class called 
MQOperations.es. 


App.Config 

To add a new application configuration file to your Windows forms project: 

1 . Right-click the project in the Solution Explorer and then select Add -» New item. Select 
Application Configuration file. Keep App.config as the name, and click Add. The new 
App.config file will open. 

2. Replace the generated XML with the XML shown in Example 5-12. This XML will be used 
to store the WebSphere MQ connection information. 

Example 5-12 Application configuration file for storing connection and resource properties 


<?xml version="1.0" encodi ng="utf-8" ?> 
<configuration> 

<appSettings> 

<add key="QmgrName" val ue="SAMPLEQM"/> 

<add key ="ConnName" value="localhost(5555)"/> 
<add key ="Channel" value="SYSTEM.DEF.SVRCONN"/> 
<add key ="InPutQ" value="0UTPUT_MSGS_Q7> 

<add key ="0utPutQ" value ="INPUT_MSGS_Q7> 
</appSettings> 

</configuration> 


3. Save and close App.config. 
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WebSphere MQ operations 

To create the MQOperations class: 

1 . Add a new class to your Windows forms project called MQOperati ons . cs . 

2. Add a reference to the project for the WebSphere MQ .NET Client library - amqmdnet.dl 1 : 

a. Right-click References in the Solution Explorer, and select Add Reference. 

b. Use the Browse tab to find MQ_instal Z\bi rAamqmdnet.dl 1 . Click OK. For example: 
C:\Program Files (x86)\IBM\WebSphere MQ\bin\amqmdnet.dll 

3. Add a reference (from the .NET tab) to System. Configuration. 

4. Add the following using statement to your class file. 

using IBM.WMQ; 

using System. Configuration; 

5. Replace the generated code for the MQOperations class shown in Example 5-13 to 
perform to the MQOperations class. 

Example 5-13 MQQueueManager code 

III <summary> 

III Performs all the Websphere Operations. 

Ill </summary> 
internal class MQOperations 
{ 

//WebSphere MQ Resources 
MQQueueManager QMgr = null; 

MQQueue QueueToPut = null; 

MQQueue QueueToGet = null; 

MQMessage subcriptionMsg = new MQMessageQ; 

MQPutMessageOptions pmo = new MQPutMessageOptionsQ ; 

MQGetMessageOptions gmo = new MQGetMessageOptionsQ ; 

//local variables 
String qmgrName = null; 

String connName = null; 

Stri ng channel = null; 

Stri ng i nputQ = null; 

Stri ng outputQ = null; 

III <summary> 

III Constructor. 

Ill </ summary > 
public MQOperati ons () 

{ 

ReadVal uesFromConf i g () ; 
try 


QMgr = new MQQueueManager (qmgrName, channel, connName); 

QueueToPut = QMgr.AccessQueue(outputQ, MQC.MQ00_0UTPUT + MQC . MQ00_I NQU IRE) ; 
QueueToGet = QMgr.AccessQueue(inputQ, MQC . MQ00_I NPUT_SHARED + MQC . MQ00_I NQU I RE) ; 
} 

catch (Exception e) 

{ 

throw e; 

} 

} 


III <summary> 

III Read values from the Config file. 
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/// </ summary > 

private void ReadVal uesFromConfigQ 

{ 

if (ConfigurationManager.AppSetti ngs .Count > 0) 

{ 

qmgrName = Confi gurationManager.AppSetti ngs ["QmgrName"] ; 
connName = ConfigurationManager.AppSettings[ M ConnName M ] ; 
channel = Confi gurationManager.AppSetti ngs ["Channel "] ; 
inputQ = ConfigurationManager.AppSettings["InPutQ M ] ; 
outputQ = ConfigurationManager.AppSettings["OutputQ M ] ; 

} 


III <summary> 

III PUT a Flowlnput message and then pool for FlowOutput message. 
Ill </summary> 

III <param name= l, msg ll ></param> 

III <returns></returns> 

public String SendBrokerRequest (Stri ng msg) 

{ 

Stri ng resul t = null; 

subcriptionMsg. Persistence = MQC.MQPER_PERSISTENT; 
subcriptionMsg.CharacterSet = 437; 
subcri ptionMsg.Wri teStri ng(msg) ; 

pmo. Options = MQC.MQPM0_SYNCP0INT + MQC.MQPM0_SYNC_RESP0NSE; 
//Put the message. 

QueueToPut. Put (subcriptionMsg, pmo) ; 

QMgr.Commi t () ; 

//Pool for reply, 
while (true) 

{ 

if (QueueToGet .CurrentDepth > 0) 

{ 

MQMessage response = new MQMessageQ; 

gmo.Wai tlnterval = MQC.MQEIJJNLIMITED; 

gmo. Options = MQC.MQGM0_WAIT + MQC.MQGM0_SYNCP0INT ; 

//We have a reply now, get it. 

QueueToGet. Get (response, gmo); 

if (response != null) 

{ 

//Send back msg to Subscri beToServi ce. 
result = response. ReadString(response. MessageLength) ; 
break; 

} 

} 

} 

return result; 

} 

} 


6. Save MQOperations.es. 
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This code performs the following operations: 

1 . Creates an instance of the WebSphere MQ .NET queue manager class (which results in a 
connection to the queue manager). 

2. Creates an instance of the WebSphere MQ .NET Queue class for the INPUT_MSGS_Q, 
OUTPUT_MSGS_Q, and Error queues, which results in opening the queues for PUT/GET 
operations. 

3. When the SubscribeToService form’s Subscribe button is clicked, MQOperations is 
invoked, which constructs a message with user data and puts it on a queue to trigger the 
broker message flow. 

4. Waits for an output message and when it arrives, gets the message and displays the result 
in a message window. 

Windows Forms: SubscribeToService.es 

Form actions are based on the events fired when one of the buttons (Subscribe or Clear) are 
clicked on their respective tabs. There are event handlers for buttons to perform the actions. 

During the form load event, we instantiate the MQOperations class, which connects to a 
queue manager and opens the resources (queues) under it. 

The button click event is fired whenever a Subscribe button is clicked. In the event handler, 
we construct XML data based on the user input and invoke the method on MQOperations to 
put the XML data as a message on the queue and to wait for a reply. 

The button click event is fired whenever a Clear button is clicked and clears all of the textbox 
contents on its respective tab: 

1 . Double-click the form design to open the SubscribeToService.es code. 

2. Add the following using statements: 

using System. Xml; 
using System. Xml . Li nq; 

3. Replace the SubscribeToService class code with the code in Example 5-14. Note that the 
names assigned to the button on the form correspond to the methods in the code. 

Example 5-14 Event handler code 
III <summary> 

III Codebehind for the form to handle events from it. 

Ill </summary> 

public partial class SubscribeToService : Form 

( 

MQOperations mqop = null; 

public SubscribeToService() 

( 

Ini ti al izeComponent () ; 

} 

III <summary> 

III Clear all the Textbox entries on tab. 

Ill </summary> 

III <param name="sender"></param> 

III <param name="e"></param> 

private void btnNewCustClear_Click (object sender, EventArgs e) 

( 
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foreach (Control obj in thi s.tbNewCustomer. Control s) 

{ 

if (obj is TextBox) 

{ 

((TextBox) obj) .Clear() ; 

} 

} 

} 

/// <summary> 

III Clear all the Textbox entries on the tab. 

Ill </summary> 

III <param name= l, sender ll ></param> 

III <param name= l, e ll ></param> 

private void btnExi stCustCl ear_Cl i ck(object sender, EventArgs e) 

{ 

foreach (Control obj in tbCustomerExi st. Control s) 

{ 

if (obj is TextBox) 

{ 

((TextBox) obj) .Clear() ; 

} 

} 

} 

III <summary> 

III Existing Customer subscribed for the service. Call the flow. 
Ill </summary> 

III <param name= l, sender ll ></param> 

III <param name= l, e ll ></param> 

private void btnExi stCustSub_Cl i ck(object sender, EventArgs e) 

{ 

try 

{ 

String result = "Request Submitted!, Activity Number = 11 ; 

Form current = this.FindForm() ; 
current. UseWaitCursor = true; 

XElement request = new XElement( M SapBapiCustomerGetdetail 1", new 
XE1 ement ("Customerno" , txtCus tNo. Text .Trim () )) ; 

String xml = mqop.SendBrokerRequest(request.ToStringO) ; 

Xml Document doc = new Xml Document () ; 
doc. LoadXml (xml ) ; 

result = result + doc. DocumentEl ement . InnerText; 
current. UseWaitCursor = false; 

MessageBox.Show(resul t, "Submi tted" , MessageBoxButtons .OK) ; 
current. UseWaitCursor = false; 

btnExi stCustCl ear_Cl i ck(nul 1 , null); 

} 

catch (Exception ex) 

{ 

MessageBox.Show(ex.ToStri ng() ) ; 
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} 

} 

/// <summary> 

III Form load event. 

Ill Perform MQ Init operation during form load. 

Ill </summary> 

III <param name= l, sender ll ></param> 

III <param name= l, e ll ></param> 

private void Subscri beToServi ce_Load(object sender, EventArgs e) 

{ 

try 

{ 

mqop = new MQOperati ons () ; 

} 

catch (Exception ei) 

{ 

MessageBox.Show(ei .ToStringO) ; 

} 

} 

III <summary> 

III New Customer subscibed for the Service. Call the Flow. 

Ill </summary> 

III <param name= l, sender ll ></param> 

III <param name= l, e ll ></param> 

private void btnNewCustSubscri be_Cl ick(object sender, EventArgs e) 

{ 

try 

{ 

Form current = this.FindForm() ; 
current. UseWaitCursor = true; 

XElement request = new XE1 ement ("SapBapiCustomerCreatefromdatal", 

new XE1 ement ("SapPi Personal datal389002469" , 

new XE1 ement ( 11 F i rstname" , tbNewCustFName.Text.Trim()) , 

new XE1 ement ("Lastname" , tbNewCustLName.Text.Trim()) , 

new XE1 ement ("Street" , tbNewCustAddrl.Text.Trim()) , 

new XE1 ement ("Ci ty" , tbNewCustCity.Text.Trim()) , 

new XElement("PostlCodl", tbNewCustZi p.Text .Trim()) , 

new XE1 ement ("Country" , tbNewCustCountry .Text .Trim() ) , 

new XElement("Region", tbNewCustSt.Text.Trim()) , 

new XE1 ement ("LanguP" , "EN"), 

new XE1 ement ("Langup I so" , "EN"), 

new XE1 ement ("Currency" , "USD")), 

new XE1 ement ("SapPi Copy reference" , 

new XElement("Salesorg", "0001"), 

new XE1 ement ("Di strChan" , "01"), 

new XElement("Division", "01"), 

new XE1 ement (" Ref Custmr" , "0000000011"))); 

String msg = mqop. SendBrokerRequest (request . ToStringO) ; 

current. UseWaitCursor = false; 

MessageBox. Show (msg, "Submi tted" , MessageBoxButtons .OK) ; 
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btnNewCustCl ear_Cl i ck(nul 1 , null); 

} 

catch (Exception exx) 

( 

MessageBox. Show (exx. ToStri ng() ) ; 

} 

} 

} 


The front end application is now ready. 


5.4.3 Running the test 

Use the following procedure to build and execute the SubscribeToService project and to test 

the Message Broker’s flow: 

1 . Build the SubscribeToService project by selecting Build Build Solution. Check the 
output to ensure that there are no errors. 

2. Execute the Project by pressing Ctrl+F5. This shortcut runs the code in Visual Studio 
without the debugger. The form will open for input. 

3. On the GUI, chose the relevant input tab, either Have an Account or Create Account. 

4. Provide the input. For an existing customer, you need a valid SAP ID to test. Talk to your 
administrator to get a valid existing SAP customer number. 

5. Provide the customer number in the Customerno input field, and click Subscribe. 

6. A message box displays indicating the completion of the operation. If successful, it will 
display the CRM online activity number. If not, exception details are provided to assist you 
in recovering from the failure. 

7. You can log on to your CRM Online account, and verify if a new account with primary 
contact with relevant details is created and the data is accurate. 

8. If it is a new customer, complete the form, and click Subscribe to create a new SAP 
customer and a CRMOnline customer. 

9. A message box displays indicating the completion of the operation. If successful, it 
displays the CRM online activity number. If not, exception details are provided to assist 
you in recovering from the failure. 

10. Closing the form ends the application execution. 

5.4.4 Using the test client from the Message Broker Toolkit 

In this section, we create a Message Broker test client on the tool kit to test the flow we just 

constructed. The steps for creating the Test client are: 

1 . In the Message Broker Toolkit, right-click the message flow, and select New -» Message 
Broker Test Client, as shown in Figure 5-31 on page 158. 
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Figure 5-31 Create a Message Broker Test Client 


2. Enter a name for the test client. In our scenario, we use FlowTest, as shown in 
Figure 5-32. Click Finish. 


D New Message Broker Test Client 


New Message Broker Test Client 

Create new Message Broker Test Client: 


mmm 


Container: | BARfiles 
| FlowTest| 


Name: 


Flow organization 

P? Use default broker schema 


3 


New... 




Figure 5-32 Specify a name for the Test Client 

3. A new component called Flow Tests and a test client called FlowTest.mbtest are created, 
as shown in Figure 5-33 on page 159. 


Finish 


Cancel 
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Figure 5-33 New flow test client 


4. Double-click FlowTest.mbtest to open an Events Page to add the message flow test 
events. See Figure 5-34. 


Events 

© There is no message flow selected to test, You may click on the message flow link to add message flows to test client, 

Message Flow Test Events ► General Properties 


► | F 0I I 3 1 B @ 

L Invoke Message Flow 


▼ Detailed Properties 


Message flow: 

Input node: <None> 



Figure 5-34 Add message flow test events 


5. Click the Enqueue button (Figure 5-35) to add an Enqueue event, which will put a 
message on to the WebSphere MQ queue. 



Figure 5-35 Enqueue button 

6. Click the Dequeue button (Figure 5-36 on page 160) three times to add three Dequeue 
events to retrieve the messages from the queue. 
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Figure 5-36 Dequeue button 

The results are shown in Figure 5-37. 
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Figure 5-37 Define Enqueue and Dequeue properties 


7. Select each Enqueue and Dequeue event, and configure it with the connection and queue 
information. 

There are four events: 

- Enqueue: Put an input message into INPUT_MSGS_Q 

- Dequeue: Get flow output from OUTPUT_MSGS_Q 

- Dequeue: Get Flow Error message from FLOW_ERROR_MSGS 

- Dequeue: Get SAP Error message from SAP_ERROR_MSGS 

For all the events, only the queue names are different. The rest of the properties remain 
the same. 

8. Now you are ready to test. 

Example 5-15 shows sample input data in the case of an existing customer. 

Example 5-15 Sample Input data in case of Existing Customer 

<SapBapi CustomerGetdetai 1 1> 

<Customerno>000000</Customerno> 

</SapBapi CustomerGetdetai 1 1> 


Example 5-16 on page 161 shows sample input data in the case of a new customer. 


160 


Using WebSphere Message Broker V8 in Mid-Market Environments 


Example 5-16 Sample Input data in case of New Customers 


<SapBapiCustomerCreatefromdatal> 
<SapPi Personal datal389002469> 
<Fi rstname>xxxx</Fi rstname> 
<Lastname>xxxx</Lastname> 
<Street>xxxx Rd</Street> 
<City>xxxx</City> 

<Postl Codl>xxxx</Postl Codl> 
<EMai l>xxxx@xxxx.com</EMai 1> 
<Country>xxxx</Country> 

<Regi on>xxxx</Regi on> 
<LanguP>xxxx</LanguP> 
<LangupIso>xxxx</LangupIso> 
<Currency>xxxx</Currency> 
</SapPi Personal datal389002469> 
<SapPi Copyreference> 

<Sal esorg>xxxx</Sal esorg> 

<Di strChan>xxxx</Di strChan> 

<Di vi si on>xxxx</Di vi si on> 
<RefCustmr>xxxxxx</RefCustmr> 
</SapPi Copyreference> 
</SapBapiCustomerCreatefromdatal> 


Select Enqueue, copy the sample data into the message box, and click SendMessage to 
trigger the message flow. 

9. Use the WebSphere MQ Explorer to monitor the output queues for messages. After a 
message arrives in any output queue, select Dequeue for the relevant queue, and click 
Get Message to display the message. 


5.5 Troubleshooting tips 

In this section, we discuss some common errors that you might encounter and some tips to 

overcome them. 

Always check if there are any messages in the error queues. Often message data contains 

exception details that are straightforward, and any issues can be fixed quickly. 

Message flow fails to build 

If the message flow fails to build: 

1 . Ensure that all of the properties are correctly set on the nodes. All mandatory properties 
are suffixed with an asterisk (*). Failing to set any such property causes a message flow 
build error. 

2. Ensure that the queues, assemblies, and adapter connection parameters set on the node 
properties are valid and can be accessed. If a network resource is used, ensure that you 
have necessary access to it. 

3. Ensure that methods, classes, and module names provided in the node properties match 
those in the code behind them. 

4. Ensure that all in and out terminals are correctly connected. 

5. Ensure that all the project prerequisites are met, for example, to use CRM Online you must 
have installed Windows Identity Foundation. 
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Message flow fails during deployment 

If the message flow fails during deployment: 

1 . Ensure that the .NETCompute node’s assembly property is set to a valid, existing 
assembly. 

2. Ensure that all of the dependencies of the .NET assembly are accessible. The broker tries 
to load all of the dependency libraries for the given assembly. 

3. Ensure that your SAP system is accessible and that you provided a valid user ID and 
password. 

4. Ensure that you set mqsichangeparams and mqsisetdbparams on the broker after 
creating the SAP Adapter connection. 

5. Ensure that there are no unresolved Schemas within the project in the Schema tree. 

Failure in SAP nodes 

If your message flow experiences a failure in one of the SAP nodes: 

1 . Ensure that the element names in the message match the element names in the schema. 
For example Customerno in <Customerno> must match the element name from 
SapBapiCustomerGetdetaill .xsd in the schema. You might also want to check that the 
names and mappings are correct in the schema file. 

2. Each of the SAP BAPI requests have a few mandatory fields for querying. For example, 
Firstname, City, PostalCode, and so on are mandatory fields to create a new customer 
record. Ensure that all of the fields are provided. Refer to SAP BAPI documentation for 
SapBapiCustomerCreatefromdatal , SapBapiCustomerChangefromdatal , and 
SapBapiCustomerGetdetailsfromdatal for a complete list of mandatory fields. 

3. Each of the fields in a BAPI request message, such as firstname and lastname in the xsd 
files under Schema, have fixed lengths. Ensure that the input is within the defined limits. 

4. If querying the BOR for BAPI interface runs endlessly, there is either a huge amount of 
data to discover and network latency is causing delays or you did not apply a correct filter 
on BOR before querying it. It is recommended to query BOR with a filter; otherwise, it will 
try to discover all of the objects in the SAP system. 

Failure in a .NETCompute node 

If you have a failure in a .NETCompute node: 

1 . Ensure that you provided a relevant class name without a .cs extension in the node 
properties. 

2. Ensure that the database is active and accessible and that the connectionstring can trace 
it. 

3. Ensure that you have a valid Windows Live ID that was used to create a CRM Online 
account. 

4. Ensure that you provided the correct CRM Online server name. 

5. Ensure that the SAPRetrieve node is providing valid customer details. If not, the .NET 
node might fail while parsing the SAP output. 
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Scenario: Integration Windows 
Communication Foundation in 
message flows - Part 1 


Windows Communication Foundation (WCF) is a distributed application interface (API) that is 
part of Microsoft’s .NET framework. WCF allows independent applications to interoperate 
across a network through a message passing interface. 

In this chapter, we introduce WCF through the implementation of an example service for 
processing insurance claims. This WCF service is consumed by a WebSphere Message 
Broker message flow to expose the WCF service to a a wide range of enterprise applications 
as part of an Enterprise Service Bus (ESB). The message flow will be created in Chapter 7, 
“Scenario: Integrating Windows Communication Foundation in message flows - Part 2” on 
page 273. 

In this chapter, we show you how to implement a WCF service, how to automatically generate 
WCF client code, how to alter the configuration of the bindings to change how the underlying 
messaging used by WCF acts, and we also discuss various hosting options that are available 
for WCF services. 


Additional materials: The .NET class code for this scenario can be downloaded from the 
IBM Redbooks publication web site. See Appendix A, “Additional material” on page 485 for 
more information. 


© Copyright IBM Corp. 2012. All rights reserved. 
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6.1 ClaimsProcessingWcfService overview 


The scenario developed in this chapter (Figure 6-1) represents an application used by a 
fictional insurance company to process insurance claims. The insurance company provides 
insurance policy products from a range of financial partners transparently under a single 
brand. 



Figure 6-1 The CiaimsProcessingWCFService Overview 


The system consists of several business objects that operations can be performed on, which 
are: 


Customers A logical representation of a customer in the system. These can be 

customers who actually bought an insurance policy or family members 
who were added to insurance policies owned by other customers. 

Policies When a customer purchases an insurance policy, all of the information 

associated with the insurance policy is stored in a Policy object. This 
includes standard information about the policy, such as the value 
covered under the policy and any excess that a customer needs to pay 
when making a claim. 

Claims If a customer needs to make a claim under their policy, perhaps 

because an accident occurred or their insured asset, such as a vehicle 
was damaged, they will contact the insurance company. This results in 
a Claim object being raised that contains all of the details of the claim, 
such as a description of what happened and the total cost of the claim. 
A claim can be approved or rejected by agents working at the 
insurance company. 

Payments If a claim is approved by an agent working for the insurance company, 

a payment needs to be issued to the customer. Because the insurance 
company offers a range of products from various financial partners, 
each Payment object must be sent to the appropriate partner 
company. The Payment object therefore contains details about both 
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the customer who is the recipient of the payment and the financial 
partner who is the underwriter of the payment. 

These business objects are kept in a persistent store so that details can be accessed from 
multiple applications and physical locations. For the purpose of this example, a file system is 
used as the persistent store; however, in a real enterprise application, it is more likely that a 
database is used. 


When an operation is performed on one of these business objects, the WCF service stores 
the updated state of the objects and generates appropriate responses to return to the 
requesting application. The operations supported are: 

ViewClaim Given a claim reference number, returns all of the details associated 

with a specific Claim object. 

ViewPolicy Given a specific policy reference number, returns all of the details 

associated with a specific Policy object 

ViewOutstandingClaims 

Returns the details for all claims that are not yet approved or rejected 
by an agent. 

CreateClaim Creates a new Claim object in the system. This is used when a 

customer contacts the insurance company to make a claim against 
their insurance. 


CreatePolicy Creates a new Policy object in the system. This operation is invoked 

when a new customer buys a policy from the insurance company. 

AcceptClaim If all of the documentation associated with a claim is present and the 

claim is determined to be within the scope of the policy, an agent can 
approve the claims, resulting in a payment being made to the 
customer. 


RejectClaim If the claim is determined to not be under the scope of the policy or if 

the documentation attached to the claim is not sufficient, an agent can 
choose to reject a claim, resulting in no payment to the customer. 


6.2 Windows Communication Foundation 

Windows Communication Foundation is a framework provided by the Microsoft .NET platform 
that provides a set of Application Programming Interfaces (APIs) for building 
network-distributed applications. The WCF programming model is designed to make it easy 
to implement a service-oriented architecture (SOA) where applications are loosely coupled 
and communicate through a message passing interface. The WCF API is contained in the 
system. ServiceModel namespace and is available in .NET framework 3.0 and higher. 


Note: Because WebSphere Message Broker supports .NET framework 4.0, this chapter 
covers this version of the framework. Some of the features discussed might vary on lower 
versions of the .NET platform. 


WCF differentiates between two key application types: 

► A service, which provides some reusable unit of business logic that is exposed to other 
enterprise components. For example, in this chapter you develop a WCF service that 
exposes various operations for processing insurance claims. 
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► A client, which is an application that consumes a service. 

Using an SOA-based approach, composite services can be constructed to act as clients of 
multiple services, exposing rich business functions to the end users of the distributed 
application. 

When developing applications that are distributed in the network, it is important that the 
communication between clients and services is loosely coupled so that, for example, changes 
to the service implementation do not require changes to all of the clients consuming the 
service. This is particularly important in an enterprise where the original author of the service 
might not even know about all consumers of the service. The WCF programming model 
ensures that communication between client and service takes place through a defined 
interface or contract that allows this loose coupling. Further, clients and services do not even 
need to be developed in the same programming language to interoperate. In some cases, 
when using web services based bindings, the client does not even need to be a .NET 
application. 

Another common pain point when developing distributed applications is dealing with the 
transport mechanism. In traditional application development, the choice of underlying 
transport mechanism is integrated into the application logic itself. This makes it challenging to 
either integrate the application with diverse clients or to change the underlying transport layer 
without developing a significant amount of plumbing or infrastructure. In WCF, the choice of 
underlying transport is abstracted away from the programming model and is determined 
through the configuration of the application at runtime. This means that the developer of the 
WCF services or clients does not need to deal with any transport layer code at all. This also 
has the advantage that the choice of transport can be altered after development of the 
application, meaning that the deployment strategy does not need to be known up front during 
development. 

6.2.1 WCF ABCs 

Although clients and services are loosely coupled, they still need to know enough about each 
other to interoperate. These details are typically referred to as an ABC specification. ABC is a 
mnemonic for the following three critical pieces of information: address, binding, and contract. 


Address 

The client needs to know the location of the service to send messages to it. An address is a 
URI of the form scheme://<host>:[port]/path with the following components: 


Scheme 

A prefix corresponding to the transport being used, for example, the 
http:// prefix indicating a HTTP based transport. 

Host 

The host name, IP address, or machine name of the system hosting 
the WCF service. 

Port 

The port the services is listening on. This parameter is optional 
because some transports have default ports and others do not use 
them at all. 

Path 

The path to the WCF service. 

Binding 



The binding specifies the transport to be used to communicate between the client and the 
service. This includes the network protocol and the mechanism for encoding and decoding 
information about the wire and any specific configuration options. WCF includes the bindings 
shown in Table 6-1 on page 167. 
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Table 6-1 Bindings provided by the .Net framework 


Binding Name 

Description 

BasicHttpBinding 

SOAP 1.1 Messages over HTTP 

BasicHttpContextBinding 

Same as BasicHttpBinding but with additional support for 
HTTP Cookies 

WsHttpBinding 

SOAP 1.1 Messages over HTTP with support for additional 
WS standards, such as WS-Addressing and 
WS-ReliableMessaging standards. 

WsHttpContextBinding 

Same as WsHttpBinding but with additional support for 
sending context information using SOAP headers. 

WsDualHttpBinding 

Same as WsHttpBinding but suitable for duplex message 
exchange patterns. 

WSFederationBinding 

SOAP over HTTP with support for the WS-Federation 
standard. 

NetTcpBinding 

TCP/IP based communication with a compact binary 
message encoding. 

NetTcpContextBinding 

Same as NetTcpBinding but with additional support for 
passing context information in headers. 

NetNamedPipeBinding 

Named Pipe based communication using a compact binary 
message encoding. 

NetPeerTcpBinding 

Peer-to-Peer based binding using TCP/IP based wire 
protocol. 

NetMsmqBinding 

Binding for enabling MOMS based communication between 
WCF Applications. 

MsmqlntegrationBinding 

Binding for integrating WCF applications with existing 
MSMQ applications. 

WebHttpBinding 

HTTP based binding using XML message encoding instead 
of SOAP. 


Contract 

The contract defines the programmatic interface between the client and the service. As a 

whole this is referred to as the service contract and is composed of two main parts: 

Operation contract The operations exposed by the service. Each operation is equivalent 
to a method on the service that can be called to invoke some piece of 
business logic. For example, in this scenario one of the operations 
defined will be ApproveClaim, which is responsible for approving an 
outstanding insurance claim and generating a payment to the 
customer. 

Data contract The data contract details which types of data the client and service 

need to be able to understand to interoperate with each other. In WCF, 
standard objects can be annotated as part of the data contract so that 
the framework automatically establishes how these are transmitted 
between client and service. 
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6.2.2 WCF operation 


After the ABC specification is defined between a client and a service, the WCF Framework 
can produce a proxy object for the service that the client can use. The proxy object exposes 
the operations defined in the service contract as method calls. This might look like a Remote 
Procedure Call (RPC) based model; however, the WCF framework uses a message-passing 
interface to implement the actual communication. 

WCF uses a serializer called the DataContract serializer to convert data sent between the 
client and the service. Depending on the binding being used, WCF might use a SOAP-based 
XML format or a binary format on the wire. The important thing to note is that this is 
completely transparent to both the client and the service. Figure 6-2 shows a high-level 
architecture diagram of a typical WCF application. 



6.3 Developing the WCF Service 

In this section, you develop a WCF Service that processes policies and claims passed to it 
from WebSphere Message Broker in its capacity as an Enterprise Service Bus (ESB). You 
define the service contract that specifies the operations that can be called by a remote .NET 
caller and the data contract that defines how data is passed back and forth between the WCF 
Service and the remote WCF client application. You also implement the service itself using 
flat files as a data storage medium. 


6.3.1 Creating a Microsoft Visual Studio 2010 project for the WCF Service 

Visual Studio includes several Project templates for developing WCF Services, which 
automatically reference the System. ServiceModel and System. Runtime. Serialization 
namespaces required by WCF. Some sample source files and configuration files are also 
created that are refactored as the service is implemented. 

To create a Visual Studio project: 

1. Launch Visual Studio. 

2. Click File New Project. 

3. In the dialog shown in Figure 6-3 on page 169, select Visual C# WCF and then WCF 

Service Library. 

4. Fill in a name for the service and the locations you will be using to save the project and 
solution files. 
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The name of the project in this scenario is ClaimsProcessingWcfService. 



Figure 6-3 New Project dialog 

5. Click OK. 

When you finish, you can see, in the Solution Explorer view, the new project created along 
with the following default files: 

► App.config 

► IServicel.cs 

► Servicel.cs 


6.3.2 Setting the namespace for the project 

To avoid clashes with other .NET assemblies that might be referenced by the solution, set a 
unique namespace for a project. This namespace, by convention, starts with the name of the 
company as the root followed by the name of the technology. For this example, the 
namespace we use is Ibm. Broker. Example. ClaimsProcessing. 

By default the New Project Wizard creates a default namespace for the project based on the 
name of the solution. In section 6.3.3, “Modifying the classes created by the New Project 
Wizard” on page 170, the namespace of existing files is updated to the new value. To ensure 
that any new resources created in this project are in the correct namespace, set the default 
namespace for the project by following these steps: 

1 . In the Solution Explorer, select ClaimsProcessingWcfService. 

2. Right-click he icon, and select Properties. 
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3. Select the Application tab to view the Application Properties. 

4. In the Default namespace field, enter I bm. Broker. Exampl e.Cl aims Processing, as shown 
in Figure 5. 


Application 

Build 

Build Events 

Debug 

Resources 

Services 

Settings 

Reference Paths 
Signing 
WCF Options 


Assembly name: 

Defeult namespace: 

ClaimsProcessingWcfService 

Ibm . Broker . Example . ClaimsProcessing 

Target framework: 

Output type: 

.NET Framework 4 Client Profile 

jvj | Class Library |v[ 

Startup object: 

(Not set) 

v [ Assembly Information... 


Resources 

Specify how application resources will be managed: 

® Icon and manifest 

A manifest determines specific settings for an application, To embed a custom manifest, first add 
it to your project and then select it from the list below. 

Icon: 

(Default Icon) v [ ] ' 

[Embed manifest wifri default settings ~ 

O Resource file: 


Figure 6-4 Setting the default namespace for the project 


5. Save and close the properties file. 


6.3.3 Modifying the classes created by the New Project Wizard 

By default the New Project Wizard creates a WCF Service called Servicel and an interface 
called IServicel. To increase readability and maintainability of the solution, rename these 
classes with more descriptive names. 

Updating the interface class 

To rename the IServcel interface: 

1 . In the Solution Explorer, double-click IServicel .cs to load the file in the editing window: 

a. Highlight the text IServi cel, in the class declaration, on the line shown in Example 6-1 . 

Example 6-1 IServicel interface declaration 

public interface IServicel 

b. Right-click, and from the context menu, select Refactor Rename. 

c. In the Rename dialogue, enter IC1 aimsProcessi ngWcfServi ce in the New Name text 
box. 

d. Uncheck the Preview reference changes check box. 

e. Click OK. 

2. The Refactor menu will not automatically rename the file, so right-click IServicel .cs in the 
Solution Explorer, and select Rename. 
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3. Enter IClaimsProcessingWcsService.es, and then press Enter to accept the changes. 

4. Alter the namespace of the ICIaimsProcessingWcfService interface by changing the 
namespace declaration in the file to match Example 6-2. 

Example 6-2 A namespace declaration of Ibm. Broker. Example.ClaimsProcessing 
namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

5. Save the interface file. 

Renaming the service class 

To rename the Servicel class: 

1. In the Solution Explorer, double-click Servicel.cs to load the file in the editing window: 

a. Highlight the Servicel in the class declaration, on the line shown in Example 6-3. 

Example 6-3 Servicel class declaration 
public class Servicel : IServicel 

b. Right-click, and from the context menu, select Refactor Rename, as shown in 
Figure 6-5. 


// NOTE: You 

can use 

the ’’Rename 11 command on the 

’’Refactor 

" menu to change the 

class name "Servicel”' in both code 

public class 
{ 

Servicel 

- TCorrrl rol 






Refactor 

► 

Rename... 

Ctrl-m, Ctrl+R 




Organize Usings 

► 

Extract Method . . . 

Ctrl+R. r Ctrl+M 



Figure 6-5 Using the Refactor menu to rename the Servicel class 


c. In the Rename dialogue, enter Cl aimsProcessi ngWcfServi ce in the New name text box. 

d. Uncheck the Preview reference changes check box. One of the advantages of using 
the Refactor menu is that any references to Servicel in the project are automatically 
updated. By unchecking this box all changed references are automatically accepted. 
Ensure that the completed dialogue box matches the example in Figure 6-6. 


Rename 

00 

New name: 




ClaimsProcessingWcfService 


Location: 




ClaimsProcessingWcfService 



I I Preview reference changes 
I~1 Search in comments 
I I Search in strings 


OK | | Cancel 


Figure 6-6 Rename dialog 

e. Click OK. 

2. The Refactor menu does not automatically rename the file, so right-click Servicel .cs in the 
Solution Explorer, and select Rename. 
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3. Enter ClaimsProcessingWcfService.es, and then press Enter to accept the changes. 

4. Alter the namespace of the ClaimsProcessingWcfService class by changing the 
namespace declaration in the file to match Example 6-4. 

Example 6-4 A namespace declaration of Ibm.Broker.Example.ClaimsProcessing 
namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 


5. Save the file. 

The New Project Wizard generates a comment in both the interface and the service class, 
indicating that they must be renamed. Because this is completed, you can remove the 
comment shown in Example 6-5 from both ClaimsProcessingWcfService.es and 
ICIaimsProcessingWcfService.es. 

Example 6-5 Generated comment 

// NOTE: You can use the "Rename" command on the "Refactor" menu to change the 
interface name "IServicel" in both code and config file together. 


Notice that code is generated for some default WCF operations. This code is removed when 
you define the DataContract and Service Operations for the service in section 6.3.6, 
“Designing and implementing the service contract” on page 184. 

Updating App.Config 

The last step is to update the service name in App.config file with the new namespace: 

1 . In the Solution Explorer, double-click App.config to open it in the editor. 

2. Replace the service name with the following syntax: 

<service name= " Ibm. Broker. Example. Cl aims Processing. Cl aimsProcessi ngWcfService"> 


6.3.4 Creating the required datatypes 

Much of the information used by the WCF service is common across operations. It is 
therefore beneficial to create custom datatypes for some of the common objects that the 
service will be operating upon. The following datatypes are required for this service: 

► Customer 

This datatype is used to hold all of the required data that represents a customer in the 
system. The customer is identified throughout the system by a unique ID number. 

► InsurancePolicy 

The InsurancePolicy Datatype represents an insurance policy that was purchased by a 
Customer. This might be one of several predefined policy offerings, identified in this 
example by the combination of a Policy Name and a Policy Provider. A policy is uniquely 
identified in the system by a Policy Number. 

► Claim 

This datatype represents a claim made by a Customer against their insurance Policy. A 
Claim is uniquely identified by a Claim Reference number and can be approved or rejected 
by an agent working for the insurance broker. 
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► Payment 

When a Claim is approved, this results in a Payment being generated to the Customer. 
This payment is processed by another system; however, the WCF service is responsible 
for generating the information required to make the payment. 

Customer Datatype 

To create the Customer Datatype: 

1 . Select Project Add Class. 

2. In the dialog box, enter Customer.es for the Name field. 

3. Click Add. 

4. A new file named Customer.es is added to the project. The class is automatically created 
in the WCF Service’s name space, and the class is opened in the editor. Replace the 
generated code with the code shown in Example 6-6 to Customer.es. 

Example 6-6 Customer.es 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

using System. Col lections; 

using System. Xml .Serial ization; 

using System. Col lections. ObjectModel ; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

[Xml Root ("Customer")] 
public class Customer 
{ 

//members 

private string _FirstName; 

private string _Surname; 

private Collection<String> _OtherNames; 

private string _Address; 

private string _CustomerId; 

private string _Email; 

publ i c Customer () 

{ 

_OtherNames = new Collection<String>(); 

} 

[DataMember] 

public string FirstName 

{ 

get { return _FirstName; } 
set { _FirstName = value; } 

} 

[DataMember] 
public string Surname 
{ 

get { return _Surname; } 
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set { _Surname = value; } 


} 

[DataMember] 

[Xml Array I tem ( 11 Name 11 ) ] 
public Col lection<String> OtherNames 
{ 

get { return _OtherNames; } 
set { _OtherNames = value; } 

} 

[DataMember] 
public string Address 
{ 

get { return _Address; } 
set { _Address = value; } 

} 

[DataMember] 

public string Customerld 

{ 

get { return _CustomerId; } 
set { _CustomerId = value; } 

} 

[DataMember] 
public string Email { 

get { return _Email; } 
set { _Email = value; } 

} 

public Boolean Equal s (Customer customer) 

{ 

if (customer. Customerld == Customerld && 
customer. FirstName == FirstName && 
customer. Surname == Surname && 
customer. OtherNames. Count == OtherNames. Count) 

{ 

foreach (string Name in OtherNames) 

{ 

if (Icustomer. OtherNames. Contains (Name)) return false; 

} 

return true; 

} 

return false; 

} 


} 


} 


5. Save Customer.es. 

Note that the class is marked with the [DataContract] attribute, and the properties are marked 
with the [DataMember] attribute. These attributes are discussed in more depth in section 
“Data contracts” on page 185. 

Similarly, the class has an [XmlRoot] attribute, and certain attributes have additional attributes 
relating to the System.Xml. Serialization namespace. These attributes specify details of how 
these datatypes are serialized to Xml and are discussed in more depth in section “XML 
serialization attributes” on page 181. 
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Also note that because this class overrides the boolean Object.equals() method so that two 
customers can be compared for equality. In this case two customers are treated as equal if 
their customer IDs match and they have the same first and last names and the complete list of 
other names matches in any order. 

Policy Datatype 

To create the Policy Datatype: 

1 . Select Project ->• Add Class. 

2. In the dialog box, enter lnsurancePolicy.es. 

3. Click Add. 

4. A new file named lnsurancePolicy.es is added to the project. The class is automatically 
created in the WCF Service’s name space. 

Replace the generated code in InsurancePolicy with the code shown in Example 6-7. 

Example 6-7 lnsurancePolicy.es 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

using System. Xml .Serialization; 

using System. Col lections. ObjectModel ; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] [Xml Root ("Pol i cy")] 
public class InsurancePolicy 
{ 

// members 

private string _Pol icyNumber; 

private Customer _Pol i cyhol der; 

private Collection<Customer> _NamedParties; 

private string _PolicyName; 

private int _Pol icyCover; 

private int _Pol icyExcess; 

private DateTime _Pol i cyStartDate; 

private DateTime _Pol icyExpiryDate; 

private String Underwriter; 

public InsurancePol icy() 

{ 

_NamedParties = new Col lection<Customer>() ; 

} 

[DataMember] 

public string Pol icyNumber 

{ 

get { return _Pol i cyNumber; } 
set { _Pol i cyNumber = value; } 

} 

[DataMember] 

public Customer Policyholder 

{ 
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get { return _Pol i cyhol der; } 
set { _Poli cyhol der = value; } 

} 

[DataMember] [Xml Array Item ("Customer")] 
public Col lection<Customer> NamedParties 
{ 

get { return _NamedParties; } 
set { _NamedParties = value; } 

} 

public void AddNamedParty (Customer customer) 

{ 

_NamedParti es .Add (customer) ; 

} 

[DataMember] 

public string PolicyName 

{ 

get { return _PolicyName; } 
set { _PolicyName = value; } 

} 

[DataMember] 
public int PolicyCover 
{ 

get { return _Pol i cyCover; } 
set { _Poli cyCover = value; } 

} 

[DataMember] 

public int PolicyExcess 

{ 

get { return _Pol icyExcess; } 
set { _Pol i cyExcess = value; } 

} 

[DataMember] 

public DateTime Pol icyStartDate 

{ 

get { return _Pol i cyStartDate; } 
set { _Pol i cyStartDate = value; } 

} 

[DataMember] 

public DateTime Pol icyExpiryDate 

{ 

get { return _Pol i cyExpi ryDate; } 
set { _Pol i cyExpi ryDate = value; } 


[DataMember] 

public String Underwriter 

{ 

get { return Underwriter; } 
set { Underwriter = value; } 

} 

} 

} 


5. Save lnsurancePolicy.es. 
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Claim Datatype 

To create the Claim Datatype: 

1 . Select Project -» Add Class. 

2. In the dialog box, enter Cl aim. cs. 

3. Click Add. 

4. A new file named Claim.cs is added to the project. The class is automatically created in 
the WCF Service’s name space. 

Replace the generated code in Claim.cs with the code shown in Example 6-8. 

Example 6-8 Claim.cs 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

using System. Xml .Serialization; 

namespace Ibm. Broker . Exampl e. Cl aimsProcessi ng 

{ 

//Claim states 
[DataContract] 
public enum ClaimState 
{ 

[EnumMember] 

Approved, 

[EnumMember] 

Rejected, 

[EnumMember] 

Submi tted 

}; 


[DataContract] [Xml Root ("Cl aim")] 
public class Claim 
{ 


//members 

private string _C1 aimReference; 
private DateTime _ClaimReceivedDate; 
private DateTime _ClaimDate; 
private int _ClaimValue; 
private Customer _Customer; 
private string _Description; 
private string _Pol icyNumber; 
private ClaimState _Status; 
private string _Notes; 

[DataMember] 

public string Cl aimReference 

{ 

get { return _C1 aimReference; } 
set { _C1 aimReference = value; } 

} 
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[DataMember] 

public DateTime ClaimReceivedDate 

{ 

get { return _ClaimReceivedDate; } 
set { _ClaimReceivedDate = value; } 

} 

[DataMember] 

public DateTime ClaimDate 

{ 

get { return _ClaimDate; } 
set { _ClaimDate = value; } 

} 

[DataMember] 
publ i c i nt Cl aimVal ue 
{ 

get { return _C1 aimVal ue; } 
set { _C1 aimVal ue = value; } 

} 

[DataMember] 

public Customer Customer 

{ 

get { return _Customer; } 
set { _Customer = value; } 

} 

[DataMember] 

public string Description 

{ 

get { return _Description; } 
set { _Description = value; } 

} 

[DataMember] 

public string PolicyNumber 

{ 

get { return _Pol i cyNumber; } 
set { _Pol i cyNumber = value; } 

} 

[DataMember] 

public ClaimState Status 

{ 

get { return _Status; } 
set { _Status = value; } 

} 

[DataMember] 
public string Notes 
{ 

get { return _Notes; } 
set { _Notes = value; } 

} 
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} 


} 


5. Save Claim.cs. 

This file also defines an enumeration named ClaimState that is used to hold the valid values 
of the Status property. Each member of the enumeration is marked with the [EnumMember] 
attribute that is required in order for the serializers used in the scenario to correctly serialize 
the Status property of Claim objects. 

Payment Datatype 

To create the Payment Datatype: 

1 . Select Project -» Add Class. 

2. In the dialog box, enter Payment.es. 

3. Click Add. 

4. A new file named Payment.es is added to the project. The class is automatically created in 
the WCF Service’s name space. 

Replace the generated code with the code shown in Example 6-9. 

Example 6-9 Payment.es 


using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

using System. Xml .Serial ization; 


namespace I bm. Broker. Exampl e. Cl aims Process i ng 

{ 

[DataContract] 

[Xml Root ("Payment")] 
public class Payment 
{ 

// members 

private Customer _Payee; 
private int _Amount; 
private string Underwriter; 

[DataMember] 
public Customer Payee 
{ 

get { return _Payee; } 
set { _Payee = value; } 

} 

[DataMember] 
public int Amount 
{ 

get { return _Amount; } 
set { _Amount = value; } 

} 
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[DataMember] 

public string Underwriter 

{ 

get { return -Underwriter; } 
set { -Underwriter = value; } 

} 


} 


5. Save Payment.es. 

6.3.5 Creating private methods to serialize and deserialize the Datatypes 

To persist data between invocations, the WCF service reads and writes objects to a local 
filesystem. The process of writing an object from an in-memory representation to a stream of 
bytes suitable for being written to disk is called serialization. Similarly the process of 
converting a series of bytes from an input stream, such as a file into an in-memory 
representation of an object, is called deserialization. 

In this example, objects are serialized using the XmlSerializer, which is part of the 
System.Xml. Serialization namespace. This means that data is written in XML format. 

In memory, a Customer object called cust looks like the example in Figure 6-7. 
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Figure 6-7 A Customer object viewed in the Visual Studio debugger 


When serialized into an XML file on the file system, this same customer object can be 
represented as shown in Example 6-10. 

Example 6-10 A Customer object serialized to XML. 

<?xml version="1.0"?> 

<Customer xml ns :xsi = " http://www.w3.org/2001/XMLSchema-i nstance" 
xml ns :xsd=" http://www.w3.org/2001/XMLSchema"> 
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<Fi rstName>John</Fi rstName> 

<Surname>Doe</Surname> 

<OtherNames> 

<Name>James</Name> 

<Name>Jeffrey</Name> 

</OtherNames> 

<Address>l Generic Street, Any Town, USA</Address> 
<CustomerId>CUST00001</CustomerId> 

<Emai 1 > j ohndoeQi tso . exampl e . i bm. com</Emai 1 > 
</Customer> 


Here, each public property is represented as an XML element with a corresponding name 
and value. The ArrayList<string> OtherNames is represented as an XML element called 
<OtherNames> with a child element representing each member of the ArrayList. 

XML serialization attributes 

The XmlSerializer automatically serializes all public members. The representation produced 
by an XmlSerializer is controlled by a selection of attributes added to the class declaration 
and public properties. In this example, the default serialization scheme is used for most 
purposes, but the [XmlRoot] attribute is used to set the name of the root element of the XML 
tree. This attribute takes an argument specifying the name of the root element, for example 
[XmlRoot(myRootElement)]. In most cases, this is set to the same value as the class name 
itself; however, when you created the InsurancePolicy class, shown in Example 6-1 1 , the 
[XmlRoot] tag was set to create an XML root element named Policy. 

Example 6-11 Setting the XML root to “ Policy ” in lnsurancePolicy.es 

[DataContract] [Xml Root ("Pol icy")] 
public class InsurancePolicy 


A serialization of an InsurancePolicy object therefore produces XML output, as shown in 
Example 6-12. 

Example 6- 12 Serialized InsurancePolicy object 
<?xml version="1.0 l, ?> 

<Pol icy xml ns :xsi = 11 http://www.w3.org/2001/XMLSchema- instance 11 
xml ns :xsd= 11 http://www.w3.org/2001/XMLSchema"> 

<Pol i cyNumber>P0LICY0001</Pol i cyNumber> 

<Pol i cyhol der> 

<Fi rstName>John</Fi rstName> 

<Surname>Doe</Surname> 

<0therNames> 

<Name>James</Name> 

<Name>Jeffrey</Name> 

</0therNames> 

<Address>l Generic Street, Any Town, USA</Address> 
<CustomerId>CUST00001</CustomerId> 

<Emai 1 >j ohndoeQi tso . exampl e . i bm. com</Emai 1 > 

</Pol i cyhol der> 

<NamedParties> 

<Customer> 

<Fi rstName>Sam</Fi rstName> 

<Surname>Doe</Surname> 

<0therNames> 
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<Name>Stephen</Name> 

<Name>John</Name> 

</OtherNames> 

<Address>l Generic Street, Any Town, USA</Address> 
<CustomerId>CUST00002</CustomerId> 

<Emai 1 >samdoe@i tso . exampl e . i bm. com</Emai 1 > 

</Customer> 

<Customer> 

<Fi rstName>Jane</Fi rstName> 

<Surname>Doe</Surname> 

<OtherNames> 

<Name>Jil 1</Name> 

<Name>Jenny</Name> 

</OtherNames> 

<Address>l Generic Street, Any Town, USA</Address> 
<CustomerId>CUST00003</CustomerId> 

<Emai 1 >j anedoe@i tso . exampl e . i bm. com</Emai 1 > 

</Customer> 

</NamedParties> 

<Pol i cyCover>1000</Pol i cyCover> 

<Pol i cyExcess>150</Pol i cyExcess> 

<Pol i cyStartDate>20 12-03-22T13 : 51 : 58. 640625+00 :00</Pol i cyStartDate> 
<Pol i cyExpi ryDate>2013-03-22T13 : 51 : 58.640625+00 : 00</ Pol i cyExpi ryDate> 
<Underwriter>Partner Insurance Company A</Underwri ter> 

</Pol i cy> 


Because the Customer datatype is itself serializable, any nested instances of these objects 
are included in the serialization of the InsurancePolicy object. 

Creating serializers for datatypes 

Each XmlSerializer object can serialize and deserialize one specific datatype; therefore, to 
persist Customer, Claim, and Policy objects to disk three different XmlSerializers is created 
for the WCF service. To reduce computational cost associated with recreating objects, these 
XmlSerializers are defined as private members of the ClaimsProcessingWcfService class 
and instantiated in the constructor. 

Add the code shown in Example 6-13 to ClaimsProcessingWcfService.es, starting at the end 
of the using statements. 

Example 6-13 XmlSerializer declare tion in ClaimsProcessing Wet Service, cs 

using System. 10; 

using System. Xml .Serial ization; 

using System. Global ization; 

private XmlSerializer CustomerSerial izer; 
private XmlSerializer Pol icySerial izer; 
private XmlSerializer ClaimSerial izer; 

publ ic ClaimsProcessingWcfService() 

{ 

CustomerSerial izer = new Xml Serial izer (typeof (Customer)) ; 

Pol icySerial izer = new Xml Serial izer (typeof (InsurancePol icy)) ; 
ClaimSerial izer = new Xml Serial izer (typeof (Claim)) ; 

} 
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Serializing an object is performed by invoking the serialize method on a suitably typed 
XmlSerializer passing in a stream to write to and the object to be serialized. Similarly invoking 
the deserialize method on a suitably typed XmlSerializer returns the deserialized object. 

Implementing the private methods for serialization and deserialization 

To create a method to serialize Customer objects, add the code shown in Example 6-14 to 
ClaimsProcessingWcfService.es. 

Example 6-14 Private method for serializing Customer objects 

private void WriteCustomerToFile(Customer CustomerToSave, String Dir) 

{ 

using(Stream fStream = new Fi 1 eStream(Di r + "\\" + CustomerToSave. Customerld, 
FileMode.Create, FileAccess. Write, FileShare.None)) 

{ 

CustomerSeri al i zer . Seri al i ze (fStream, CustomerToSave) ; 

} 

} 


In this method, a new FileStream is created based on the Dir input parameter concatenated 
with the Customerld. So for example, if the string C:\path\to\save was passed in and the 
customerld was CUST0001 , the object is serialized to a file called 
C:\path\to\save\CUST0001. Note that because the backslash character is an escape 
character, we must escape it when entering it into a string. 

The FileStream object is created with the FileMode.Create, FileAccess.Write, and 
FileShare.None attributes to ensure that if the file does not exist it will be created. If the file 
already exists, it is overwritten, and the service has exclusive access to the file. 

The FileStream class also implements the IDisposable interface, so when the using block 
finishes executing the stream, the underlying file is automatically closed. 

To create private methods to serialize InsurancePolicy and Claim objects using the same 
pattern, add the code shown in Example 6-15 to ClaimsProcessingWcfService.es. 

Example 6-15 Private method for serializing InsurancePolicy and Claim objects 

private void WritePol icyToFile(InsurancePol icy pol icyToSave, string dir) 

{ 

using (Stream fStream = new FileStream(dir + "\\" + pol icyToSave. Pol icyNumber, 
FileMode.Create, FileAccess.Write, FileShare.None)) 

{ 

Pol icySerial i zer. Serial ize (fStream, pol icyToSave) ; 

} 

} 

private void WriteClaimToFile(Claim ClaimToSave, string Dir) 

{ 

using (Stream fStream = new Fi 1 eStream(Di r + "\\" + Cl aimToSave.Cl aimReference, 
FileMode.Create, FileAccess.Write, FileShare.None)) 

{ 

ClaimSerial izer. Serial ize(fStream, ClaimToSave) ; 

} 

} 


Chapter 6. Scenario: Integration Windows Communication Foundation in message flows - Part 1 183 







To deserialize an object, a similar pattern is used; however, this time the stream is created 
using the File.OpenRead method, which automatically sets the appropriate FileMode, 
FileAccess, and FileShare options for reading. Again, scope of the fStream object is limited to 
a single block by the using statement to take advantage of the I Disposable interface. 

Add the code shown in Example 6-16 to ClaimsProcessing WcfService.cs. This code creates 
methods to deserialize Customer, InsurancePolicy, and Claim objects. 

Example 6-16 Private methods for deserializing Customer, InsurancePolicy and Claim objects 

private Customer GetCustomerFromFi 1 e(string inputFile) 

{ 

using (Stream fStream = File.OpenRead(inputFile)) 

( 

return (Customer) CustomerSeri al izer. Deserial i ze (fStream) ; 

} 

} 

private InsurancePolicy GetPol icyFromFi 1 e (String inputFile) 

( 

using (Stream fStream = File.OpenRead(inputFile)) 

( 

return (InsurancePol i cy) Pol i cySeri al izer.Deseri al ize (fStream) ; 

} 

} 

private Claim GetClaimFromFile(String InputFile) 

( 

using (Stream fStream = File.OpenRead(InputFile)) 

( 

return (Cl aim) Cl aimSeri al izer. Deserial ize (fStream) ; 

} 

} 


6.3.6 Designing and implementing the service contract 

WCF allows applications to communicate in a transport independent manner by defining a 
service contract between clients and services. This contract covers what operations are 
exposed by the service, the operation contract, and the data model to use when calling these 
operations, the data contract. The types of errors that the client must be prepared to deal with 
can also optionally be specified using a fault contract, and this is covered in more detail in 
“Defining the Fault types” on page 208. 

Notice that after following the steps in 6.3.3, “Modifying the classes created by the New 
Project Wizard” on page 170, the New Project Wizard already marked the interface class 
ICIaimsProcessingWcfService as defining a service contract by marking the class declaration 
with the [ServiceContract] attribute. 

Operation contracts 

The operation contract defines what operations the service supports. These are exposed as 
methods marked with the [OperationContract] attribute on the Interface specifying the service 
contract. 

The New Project Wizard created two default operation contracts in 
ICIaimsProcessingWcfService when you followed the steps in section 6.3.1, “Creating a 
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Microsoft Visual Studio 2010 project for the WCF Service” on page 168. The code in 
Example 6-17 shows the two generated methods marked with the [OperationContract] 
attribute: GetData and GetDataUsingDataContract. 

Example 6-17 Operation contracts in the service interface 

[Operati onContract] 
string GetData(int value); 

[Operati onContract] 

Composi teType GetDatallsi ngDataContract (Composi teType composi te) ; 

// TODO: Add your service operations here 


The GetData declaration specifies that the service must implement an operation called 
GetData, which takes an int as a parameter and returns a string. Because only primitive types 
are used in this operation, a data contract is not required. 

The second GetDataUsingDataContract method specifies that the service must implement an 
operation called GetDataUsingDataContract, which takes a CompositeType object as a 
parameter and returns a CompositeType object to the caller. Because CompositeType is not a 
primitive type, a data contract is required so that the WCF classes can serialize and 
deserialize the customer type. 

Data contracts 

WCF uses the DataContractSerializer class to serialize and deserialize types passed 
between WCF clients and services. It does this using a data contract, which is an abstract 
description of the data types to be exchanged. 

The type used by the GetDataUsingDataContract operation is automatically defined by the 
New Project Wizard and is located just below the ICIaimsProcessingWcfService interface 
definition. The definition of the CompositeType class is shown in Example 6-18. 

Example 6-18 Data contract 

[DataContract] 

public class CompositeType 

{ 

bool bool Value = true; 
string stringValue = "Hello "; 

[DataMember] 
public bool Bool Value 
{ 

get { return bool Value; } 
set { boolValue = value; } 

} 

[DataMember] 

public string StringValue 

{ 

get { return stringValue; } 
set { stringValue = value; } 

} 

} 
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The class is marked with the [DataContract] attribute to indicate that the class implements a 
data contract. For the type to actually implement the data contract, the properties that form 
part of the DataContract must be marked with the [DataMember] attribute. 

Implementation of a service contract 

The New Project Wizard also generates a default implementation of the operation contract in 
the ClaimsProcessingWcfService.es class. Example 6-19 shows the code that implements 
the service contract. 

Example 6-19 The implementation of the automatically generated service contract 

public string GetData(int value) 

{ 

return string. Format("You entered: {0}", value); 

} 

public Composi teType GetDataUsingDataContract(CompositeType composite) 

{ 

if (composite == null) 

( 

throw new ArgumentNul 1 Exception ("composi te") ; 

} 

if (composite. BoolValue) 

( 

composi te.StringVal ue += "Suffix"; 

} 

return composite; 


These methods implement the interface specified in ICIaimsProcessingWcfService.es and 
therefore also implement the service contract. Recall that to implement the interface, the 
calling signature and return type of the concrete method must match the definition in the 
interface. 

Removing the automatically generated service contract and 
implementation 

While the automatically generated code is useful when investigating WCF for the first time, 
these methods and datatypes are not required in the Claims Processing Application. 
Therefore, to keep the code clean and make it easier to maintain these, remove methods and 
datatypes from the project before proceeding. 

To remove the automatically generated methods and datatypes from the 
ICIaimsProcessingWcfService.es and ClaimsProcessingWcfService files: 

1 . Open the file ICIaimsProcessingWcfService.es by double-clicking the icon in the Solution 
Explorer. 

2. Highlight the code shown in Example 6-17 on page 185. Click the Delete key to remove 
the highlighted code. 

3. Highlight the code shown in Example 6-18 on page 185. Click the Delete key to remove 
the highlighted code. 

ICIaimsProcessingWcfService.es now looks like the code shown in Example 6-20 on 
page 187. 
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Example 6-20 ICIaimsProcessingWcfService.es 


using System; 

using System. Col lect ions. Generic; 

using System. Li nq; 

using System. Runtime. Serial ization; 

using System. Servi ceModel ; 

using System. Text; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[Servi ceContract] 

public interface IC1 aimsProcessi ngWcfService 

{ 

} 

} 


4. Save ICIaimsProcessingWcfService.es. 

5. Select ClaimsProcessingService.es from the Solution Explorer, and double-click it to 
open the implementation class. 

6. Highlight the code shown in Example 6-19 on page 186. Click the Delete key to remove 
the highlighted code. 

ClaimsProcessingWcfService.es now looks like the example in Example 6-21. 

Example 6-21 ClaimsProcessingWcfService.es 
using System; 

using System. Col lect ions. Generic; 

using System. Li nq; 

using System. Runtime. Serial ization; 

using System. Servi ceModel ; 

using System. Text; 

using System. 10; 

using System. Xml .Serial ization; 

using System. Globalization; 

using System. Col lections. ObjectModel ; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

public class ClaimsProcessingWcfService : IC1 aimsProcessi ngWcfServi ce 

{ 

private Xml Seri al izer CustomerSerial izer; 
private Xml Serial izer Pol icySerial izer; 
private Xml Serial izer ClaimSerial izer; 

publ ic ClaimsProcessingWcfService() 

{ 

CustomerSerial izer = new Xml Serial izer (typeof (Customer)) ; 

Pol icySerial izer = new Xml Serial izer (typeof (InsurancePol icy)) ; 
ClaimSerial izer = new Xml Serial izer (typeof (Claim)) ; 

} 

private Customer GetCustomerFromFi 1 e(stri ng inputFile) 

{ 
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using (Stream fStream = File.OpenRead(inputFile)) 

{ 

return (Customer)CustomerSeri al izer. Deserial ize(fStream) ; 

} 


private void WriteCustomerToFile(Customer CustomerToSave, String Dir) 

{ 

using (Stream fStream = new FileStream(Dir + "\\" + 

CustomerToSave. Customer Id, Fi 1 eMode. Create, 

Fi 1 eAccess . Wri te , Fi 1 eShare . None) ) 

{ 

CustomerSerial izer. Serial ize(fStream, CustomerToSave) ; 

} 

} 

private InsurancePol i cy GetPolicyFromFile(String inputFile) 

{ 

using (Stream fStream = File.OpenRead(inputFile)) 

{ 

return (InsurancePol i cy) Pol i cySeri al izer.Deseri al i ze (fStream) ; 

} 

} 

private void Wri tePol i cyToFi 1 e(InsurancePol i cy pol icyToSave, 


using (Stream fStream = new FileStream(dir + "\\" + 
pol i cyToSave. Pol i cyNumber, Fi 1 eMode. Create, 

Fi 1 eAccess . Wri te , Fi 1 eShare . None) ) 

{ 

Pol i cySeri al i zer.Seri al i ze(fStream, pol i cyToSave) ; 

} 

} 

private Claim GetCl aimFromFi 1 e(Stri ng InputFile) 

{ 

using (Stream fStream = File.OpenRead(InputFile)) 

{ 

return (Claim)ClaimSerial izer. Deserial ize(fStream) ; 

} 

} 

private void WriteClaimToFile(Claim ClaimToSave, string Dir) 

{ 

using (Stream fStream = new FileStream(Dir + "\\" + 

Cl aimToSave.Cl aimReference, Fi 1 eMode. Create, 

Fi 1 eAccess . Wri te , Fi 1 eShare . None) ) 

{ 

ClaimSerial izer. Serial ize(fStream, ClaimToSave) ; 

} 
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} 


} 


} 


7. Save ClaimsProcessingServiceWcf.es. 

Designing the Claims Processing operation contract 

The Claims Processing service supports seven operation types: 

► Create a new claim 

► View an existing claim 

► View outstanding claims 

► Approve a claim 

► Reject a claim 

► View a policy 

► Create a new policy 

Each of these operations correspond to a WCF operation contract on the 
ICIaimsProcessingWcfService interface. To add the operation contracts to the interface: 

1. Open ICIaimsProcessingWcfService.es. 

2. Modify the code by adding the additional method declarations shown in Example 6-22 
after the following lines of code. 

[ServiceContract] 

public interface ICIaimsProcessingWcfService 

{ 

Example 6-22 The completed ICIaimsProcessingWcfService.es file with operation contracts 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Runtime. Serial ization; 

using System. Servi ceModel ; 

using System. Text; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[ServiceContract] 

public interface ICIaimsProcessingWcfService 

{ 


[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

NewClaimResponse Created aim(NewClaimRequest request); 

[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

ViewClaimResponse ViewClaim(ViewClaimRequest request); 

[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

[Faul tContract (typeof (Vi ewOut standi ngCl aimslncompl eteResul tsFaul t) )] 
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Vi ewOutstandi ngClaimsResponse 

Vi ewOut standi ngCl aims (Vi ewOutstandi ngCl aimsRequest request) ; 

[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

Approved aimResponse Approved aim(ApproveCl aimRequest request) ; 

[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

RejectCl aimResponse RejectClaim(RejectClaimRequest request); 

[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

ViewPol i cyResponse ViewPol icy (ViewPol icyRequest request); 

[Operati onContract] 

[Faul tContract (typeof (Cl aimProcessi ngFaul t) )] 

CreatePol i cyResponse CreatePol icy (CreatePol i cyRequest request) ; 

} 

} 


This code generates errors in the Error list, which we resolve later in “Defining the Fault 
types” on page 208. 

3. Save the file. 

The ICIaimsProcessingWcfService.es file is now in its completed state. Note that as well as 
the previously discussed [OperationContract] attribute each operation is also decorated with 
the [FaultContract] attribute. This attribute specifies how failures in the service are 
communicated to the client consuming the service, which we discuss in more detail in 
“Defining the Fault types” on page 208. 

Designing the data contract 

In 6.3.4, “Creating the required datatypes” on page 172, several basic datatypes were defined 
that are already marked with the [DataContract] and [DataMember] attributes, specifying that 
they are part of the data contract for this service. The operation contracts defined in 
“Designing the Claims Processing operation contract” on page 189 do not use these 
datatypes; however, instead they use a specific data type for the request and response 
parameters for each operation. 

Request and response base classes for data contracts 

Many parameters are common across multiple request or response types, so to reduce code 
duplication, they all inherit from one of two base types. These base types are: 

► ClaimsProcessingRequest 

This class defines the properties shown in Table 6-2. 


Table 6-2 ClaimsProcessingRequest Properties 


Property 

Purpose 

RequestDate 

A DateTime value indicating when the request was sent. 

Applicationld 

An identifier for the application making the request. 

Messageld 

A unique identifier for this message. 
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Property 

Purpose 

TypeOfRequest 

An enumeration value showing what specific type of 
request this object represents. Including the request 
type means that reflection is not required to determine 
the type of a derived class from a base class reference. 


► ClaimsProcessingResponse 

This class defines the properties shown in Table 6-3. 


Table 6-3 ClaimsProcessingResponse Properties 


Property 

Purpose 

ResponseTime 

A DateTime indicated when the response was sent 
from the Claims Processing Service back to the client. 

Correlationld 

An identifier allowing the client to correlate a request 
message with a response message. The Correlationld 
for a response is set to the Messageld of the request 
which generated it. 

TypeOfResponse 

An enumeration value showing what specific type of 
response this object represents. 


To create the base classes for the requests and responses, add the files shown in 
Example 6-23 and Example 6-24 on page 192 to your project using the Project Add class 
dialog: 

1 . Add ClaimsProcessingResponse.es, and replace the generated code with the code shown 
in Example 6-23. 

Example 6-23 ClaimsProcessingResponse. cs 
using System; 

using System. Col lect ions. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 


[DataContract] 

public enum ResponseType 

{ ^ ' 
[EnumMember] 

ApproveClaim, 

[EnumMember] 

CreatePol i cy, 

[EnumMember] 

NewCl aim, 

[EnumMember] 

RejectCl aim, 

[EnumMember] 

ViewClaim, 

[EnumMember] 

Vi ewOut standi ngCl aims, 
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[EnumMember] 

ViewPol icy, 

[EnumMember] 

Processi ng 

} 

[DataContract] 

public class ClaimsProcessingResponse 

{ 


private DateTime _ResponseTime; 
private string _CorrelationId; 

[DataMember] 

public DateTime ResponseTime 

{ 

get { return _ResponseTime; } 
set { _ResponseTime = value; } 

} 

[DataMember] 

public string Correlationld 

{ 

get { return _CorrelationId; } 
set { _CorrelationId = value; } 

} 


publ ic ClaimsProcessingResponse() 

{ 

_ResponseTime = DateTime. Now; 

} 

[DataMember] 

virtual public ResponseType TypeOfResponse 

{ 

get { return ResponseType. Processi ng; } 
//required for WCF serialization 
private set { } 

} 

} 

} 


Tip: The property TypeOfResponse is marked as virtual so that it can be overridden by 
derived classes of this base type. 


The TypeOfResponse is never set by the code. Ordinarily we can omit the setter for this 
property making it read only. However, for the serializer to work correctly, the property 
must have a setter. For this reason, the setter is declared private and does nothing. 

2. Add ClaimsProcessingRequest.es, and replace the generated code with the code shown 
in Example 6-24 on page 1 92. 

Example 6-24 ClaimsProcessingRequest.es 
using System; 
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using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 
public enum RequestType 
{ 

[EnumMember] 

Approved aim, 

[EnumMember] 

CreatePol i cy, 

[EnumMember] 

NewCl aim, 

[EnumMember] 

RejectCl aim, 

[EnumMember] 

ViewClaim, 

[EnumMember] 

Vi ewOut standi ngCl ai ms , 

[EnumMember] 

ViewPol icy, 

[EnumMember] 

Processi ng 

} 

[DataContract] 

[KnownType(typeof (Approved aimRequest))] 
[KnownType (typeof (CreatePol i cyRequest) ) ] 
[KnownType(typeof (NewCl aimRequest) )] 

[KnownType (typeof (RejectCl aimRequest) )] 

[KnownType (typeof (Vi ewCl aimRequest))] 

[KnownType (typeof (Vi ewOutstandi ngCl aimsRequest) )] 
[KnownType(typeof (Vi ewPol i cyRequest) )] 
public abstract class ClaimsProcessingRequest 
{ 

private DateTime _RequestDate; 
private string _ApplicationId; 
private string _MessageId; 

[DataMember] 

public DateTime RequestDate 

{ 

get { return _RequestDate; } 
set { _RequestDate = value; } 

} 

[DataMember] 

public string Appl icationld 

{ 

get { return _Appl icationld; } 
set { _Appl icationld = value; } 

} 
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[DataMember] 

public string Messageld 

{ 

get { return _MessageId; } 
set { _MessageId = value; } 

} 

[DataMember] 

virtual public RequestType TypeOfRequest 

{ 

get { return RequestType. Processing; } 
//required for WCF serialization 
private set {} 

} 

} 

} 


The class declaration is decorated with a [KnownType] attribute so that the 
DataContractSerializer used by WCF recognizes the listed type when serializing or 
deserializing instances of this object. Without these attributes, WCF does not correctly 
populate base class properties on derived types. 

After the base types are created, each derived type only needs to include additional 
properties available to that type and relevant to the particular operation. 

Data contract for ApproveClaim 

To approve a claim, the information shown in Table 6-4 must be provided to complete the 
request. 


Table 6-4 ApproveClaimRequestProperties 


Property 

Purpose 

ClaimReference 

The unique ID of the claim to be approved. 

Value Approved 

The value of claim approved. 

AgentReference 

An ID identifying the agent that approved this claim. 

TypeOfRequest 

Returns a constant value of RequestType.ApproveClaim to 
indicate that this is an ApproveClaimRequest. 


Create a new class in your project named ApproveClaimRequest with the contents shown in 
Example 6-25. 

Example 6-25 ApproveClaimRequest.es 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ApproveClaimRequest : ClaimsProcessingRequest 
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{ 


[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. Approved aim; } 

} 

//Approved aimRequest 
private string _C1 aimReference; 
private int _Val ueApproved; 
private string _AgentReference; 

[DataMember] 

public string Cl aimReference 

{ 

get { return _C1 aimReference; } 
set { _C1 aimReference = value; } 

} 

[DataMember] 

public int Val ueApproved 

{ 

get { return _Val ueApproved; } 
set { _Val ueApproved = value; } 

} 

[DataMember] 

public string AgentReference 

{ 

get { return _AgentReference; } 
set {_AgentReference = value; } 

} 

} 

} 


When an approval request is submitted there are two possible outcomes. Either the service 
can reject the approval by throwing a fault or the system can accept the approval and send a 
response containing payment information to the requesting client. Handling faults is covered 
in more detail in “Defining the Fault types” on page 208. 

The data contract for the ApproveClaimResponse datatype defines the properties shown in 
Table 6-5. 


Table 6-5 ApproveClaimResponse properties 


Property 

Purpose 

Payment 

A serialized Payment object containing details of the payment 
to make to the customer filing the approved Claim. 

TypeOfResponse 

Returns a constant value of ResponseType.ApproveClaim to 
indicate that this is an ApproveClaimResponse. 


Create a new class in the project named ApproveClaimResponse.es with the content in 
Example 6-26. 
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Example 6-26 ApproveClaimResponse.es 


using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class Approved aimResponse : ClaimsProcessingResponse 

{ 

[DataMember] 

public override ResponseType TypeOf Response 

{ 

get { return ResponseType. Approved aim; } 

} 

private Payment _Payment; 

[DataMember] 
public Payment Payment 
{ 

get { return _Payment; } 
set { _Payment = value; } 

} 

public ApproveClaimResponse(Payment payment) 

{ 

_Payment = payment; 

} 

} 

} 


Data contract for Create Policy 

The data contract for the CreatePolicyRequest defines the properties shown in Table 6-6 that 
are required when creating a new insurance policy in the system. 


Table 6-6 CreatePolicyRequest Properties 


Property 

Purpose 

PrimaryCustomer 

The Customer who took out the new insurance policy being 
created. 

NamedParties 

Any named parties who are also covered by this policy. 

PolicyName 

The policy name, which corresponds to a product offering 
defined in the system. 

Pol icy Cover 

The total value insured under this policy. 

PolicyExcess 

The excess payable by the customer on any claim made 
under this policy. 

TypeOfRequest 

Returns a constant value of RequestType.CreatePolicy to 
indicate that this is a CreatePolicyRequest. 
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Create a new class named CreatePolicyRequest.es in the project with the contents shown in 
Example 6-27. 

Example 6-27 CreatePolicyRequest 
using System; 

using System.Collections.ObjectModel ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class CreatePolicyRequest : ClaimsProcessingRequest 

{ 

[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. CreatePol i cy; } 

} 

private Customer _PrimaryCustomer; 

private Collection<Customer> _NamedParties; 

private string _PolicyName; 

private int _Pol icyCover; 

private int _Pol icyExcess; 

[DataMember] 

public Customer PrimaryCustomer 

{ 

get { return _PrimaryCustomer; } 
set { _PrimaryCustomer = value; } 

} 

[DataMember] 

public Col lection<Customer> NamedParties 

{ 

get { return _NamedParties; } 

} 

[OnDeserial i zing] 

private void OnDeserial izing(StreamingContext context) 

{ 

_NamedParties = new Col lection<Customer>() ; 

} 

[DataMember] 

public string PolicyName 

{ 

get { return _PolicyName; } 
set { _PolicyName = value; } 

} 

[DataMember] 

public int Pol icyCover 
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{ 

get { return _Pol icyCover; } 
set { _Pol icyCover = value; } 

} 

[DataMember] 

public int PolicyExcess 

{ 

get { return _PolicyExcess; } 
set { _Pol icyExcess = value; } 

} 

public CreatePol icyRequest () 

{ 

_NamedParties = new Col lection<Customer>() ; 

} 

} 

} 


Tip: In the default constructor, the collection is initialized. This is to prevent 
NullReferenceExceptions when a new object is created programmatically. When an object 
is deserialized by WCF the constructor is not executed. Care therefore needs to be taken 
when relying on the existence of the NamedParties property. 


The CreatePolicyResponse defines the properties shown in Table 6-7. 
Table 6-7 CreatePolicyResponse Properties 


Property 

Purpose 

Policy 

The full policy details of the newly created policy. 

TypeOfResponse 

Returns a constant value of ResponseType. CreatePolicy to 
indicate that this is a CreatePolicyResponse. 


Create a new class named CreatePolicyResponse.es in the project with the contents in 
Example 6-28. 

Example 6-28 CreatePolicyResponse 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class CreatePolicyResponse : Cl aimsProcessi ngResponse 

{ 

[DataMember] 

public override ResponseType TypeOf Response 

{ 

get { return ResponseType. CreatePol icy; } 

} 
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//CreatePol i cyResponse 
private InsurancePol i cy _Policy; 

[DataMember] 

public InsurancePol icy Policy 

{ 

get { return _Policy; } 
set { _Pol i cy = val ue; } 

} 

public CreatePol icyResponse(InsurancePol icy policy) 

{ 

_Policy = policy; 

} 

} 

} 


Data contract For NewClaim 

The NewClaimRequest datatype defines the properties shown in Table 6-8. 
Table 6-8 NewClaimRequest Properties 


Property 

Purpose 

Claim 

The full claim details of the newly created claim. 

TypeOfRequest 

Returns a constant value of RequestType. NewClaim to 
indicate that this is a NewClaimRequest. 


Create a new class named NewClaimRequest.es with the content shown in Example 6-29. 

Example 6-29 NewClaimRequest.es 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class NewClaimRequest : Cl aimsProcessi ngRequest 

{ 

[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. NewClaim; } 

} 

private Claim _NewClaim; 

[DataMember] 
public Claim NewClaim 
{ 

get { return _NewClaim; } 
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} 


set { _NewClaim = value; } 


public NewClaimRequest(Claim newRequest, string messageld, 

string appl i cati onld) 

{ 

this.NewClaim = newRequest; 
thi s. Messageld = messageld; 
this. Application^ = appl icationld; 
this.RequestDate = DateTime.Now; 

} 

} 

} 


The NewClaimResponse datatype defines the properties shown in Table 6-9. 
Table 6-9 NewClaimResponse.es 


Property 

Purpose 

TypeOfResponse 

Returns a constant value of ResponseType. NewClaim to 
indicate that this is a NewClaimResponse. 


Create a new file named NewClaimResponse.es in the project with the content in 
Example 6-30. 

Example 6-30 NewClaimResponse.es 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class NewClaimResponse : Cl aimsProcessingResponse 

{ 


[DataMember] 

public override ResponseType TypeOfResponse 

{ 

get { return ResponseType. NewClaim; } 

} 


} 


} 


Tip: The NewClaimResponse datatype does not define any additional parameters over the 
base type of ClaimsProcessingResponse; however, it does override the TypeOfResponse 
property. This pattern is repeated in some of the other response datatypes in this section. 
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Data contract for RejectClaim 

The RejectClaimRequest datatype defines the properties shown in Table 6-10. 
Table 6-10 RejectClaimRequest Properties 


Property 

Purpose 

ClaimReference 

A unique ID representing the claim being rejected. 

AgentReference 

A unique ID representing the Agent responsible for rejecting 
the claim referred to in the ClaimReference field. 

Reason 

The reason for rejecting the claim. 

TypeOfRequest 

Returns a constant value of RequestType. RejectClaim to 
indicate that this is a RejectClaimRequest. 


Create a new class named RejectClaimRequest.es with the content shown in Example 6-31 . 

Example 6-31 RejectClaimRequest.es 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class RejectClaimRequest : Cl aimsProcessi ngRequest 

{ 

[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. RejectClaim; } 

} 

private string _C1 aimReference; 
private string _AgentReference; 
private string _Reason; 

[DataMember] 

public string Cl aimReference 

{ 

get { return _C1 aimReference; } 
set { _C1 aimReference = value; } 

} 

[DataMember] 

public string AgentReference 

{ 

get { return _AgentReference; } 
set { _AgentReference = value; } 

} 

[DataMember] 
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public string Reason 

{ 

get { return _Reason; } 
set { _Reason = value; } 

} 

} 

} 


The RejectClaimResponse datatype defines the properties shown in Table 6-1 1 . 
Table 6-11 RejectClaimResponse Properties 


Property 

Purpose 

TypeOfResponse 

Returns a constant value of ResponseType. RejectClaim to 
indicate that this is a RejectClaimResponse. 


Create a new class in the project named RejectClaimResponse.es with the contents shown in 
Example 6-32. 

Example 6-32 RejectClaimResponse.es 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class RejectClaimResponse : Cl aimsProcessi ngResponse 

{ 


[DataMember] 

public override ResponseType TypeOfResponse{ 
get { return ResponseType. RejectClaim; } 

} 

} 

} 


Data contract for ViewClaim 

The ViewClaimRequest datatype defines the properties shown in Table 6-12. 
Table 6-12 ViewClaimRequest Properties 


Property 

Purpose 

ClaimReference 

A unique ID referencing the claim to view. 

TypeOfRequest 

Returns a constant value of RequestType.ViewClaim to 
indicate that this is a ViewClaimRequest. 


Create a new class named ViewClaimRequest.es with the content shown in Example 6-33. 
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Example 6-33 ViewClaimRequest.es 


using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewClaimRequest : ClaimsProcessingRequest 

{ 

[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. ViewClaim; } 

} 

private string _C1 aimReference; 

[DataMember] 

public string Cl aimReference 

{ 

get { return _C1 aimReference; } 
set { _C1 aimReference = value; } 

} 


} 


} 


The ViewClaimResponse class defines the properties shown in Table 6-13. 
Table 6-13 ViewClaimResponse Properties 


Property 

Purpose 

Claim 

The full claim details corresponding to the claim reference 
passed in the corresponding ViewClaimRequest. 

TypeOfResponse 

Returns a constant value of ResponseType. ViewClaim to 
indicate that this is a ViewClaimResponse. 


Create a new class named ViewClaimResponse.es with the content in Example 6-34. 

Example 6-34 ViewClaimResponse.es 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewClaimResponse : Cl aimsProcessi ngResponse 
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[DataMember] 

public override ResponseType TypeOf Response 

{ 

get { return ResponseType. ViewClaim; } 

} 

private Claim _Claim; 

[DataMember] 
publ i c Cl aim Cl aim 
{ 

get { return _Claim; } 
set { _Claim = value; } 

} 

public ViewClaimResponse(Claim claim) 

{ 

_Claim = claim; 

} 

} 

} 


Data contract for ViewOutstandingClaims 

The ViewOutstandingClaimsRequest datatype defines the properties in Table 6-14. 


Table 6-14 ViewOutstandingClaimsRequest properties 


Property 

Purpose 

TypeOfRequest 

Returns a constant value of 

RequestType.ViewOutstandingClaim to indicate that this is a 
ViewOutstandingClaimsRequest. 


Create a new class named ViewOutstandingClaimsRequest.es with the content in 
Example 6-35. 

Example 6-35 ViewOutstandingClaimsRequest. cs 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewOutstandingClaimsRequest : ClaimsProcessingRequest 

{ 

[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. ViewOutstandingClaims; } 

} 

} 
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} 


The ViewOutstandingClaimsResponse defines the properties in Table 6-15. 
Table 6-15 ViewOutstandingClaimsResponse 


Property 

Purpose 

OutstandingClaims 

Returns a collection of claims that are in the Submitted state. 

TypeOfResponse 

Returns a constant value of 

ResponseType. ViewOutstandingClaim to indicate that this is 
a ViewOutstandingClaimsResponse. 


Create a new class in the project named ViewOutstandingClaimsResponse.es with the 
content in Example 6-36. 

Example 6-36 ViewOutstandingClaimsResponse. cs 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

using System.Collections.ObjectModel ; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewOutstandingClaimsResponse : Cl aimsProcessi ngResponse 

{ 

[DataMember] 

public override ResponseType TypeOf Response 

{ 

get { return ResponseType. ViewOutstandingClaims; } 

} 


private Coll ecti on<Claim> _OutstandingClaims; 
[DataMember] 

public Col 1 ecti on<Claim> OutstandingClaims 

{ 

get { return _OutstandingClaims; } 

} 

[OnDeserial i zing] 

private void OnDeserializing(StreamingContext context) 

{ 

_OutstandingClaims = new Col lection<Claim>() ; 

} 

public void AddOutstandi ngCl aim(Cl aim claim) 

{ 

_Outstandi ngCl aims .Add (cl aim) ; 

} 
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publ i c Vi ewOutstandi ngCl aimsResponse() 

{ 

_OutstandingCl aims = new Col 1 ection<Cl aim>() ; 

} 

publ ic Vi ewOutstandi ngCl aimsResponse(Col 1 ection<Cl aim> outstandi ngClaims) 

{ 

_OutstandingCl aims = new Col 1 ection<Cl aim>() ; 
foreach (Claim claim in outstandingCl aims) 

{ 

_Outstandi ngCl aims. Add (cl aim) ; 

} 

} 

} 

} 


Tip: This class implements a method called onDeserializing, which is decorated with the 
[OnDeserializing] attribute. This attribute specifies that when this class is being 
deserialized by the DataContractSerializerthe decorated method is called. This method 
might have any name but it must take a StreamingContext as a parameter. 


DataContract for ViewPolicy 

The ViewPolicyRequest datatype defines the properties shown in Table 6-16. 
Table 6-16 ViewPolicyRequest Properties 


Property 

Purpose 

PolicyReference 

A unique ID representing the policy to be viewed. 

TypeOfRequest 

Returns a constant value of RequestType.ViewPolicy to 
indicate that this is a ViewPolicyRequest. 


Create a new class in the project named ViewPolicyRequest.es with the contents in 
Example 6-37. 

Example 6-37 ViewPolicyRequest 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewPolicyRequest : Cl aimsProcessi ngRequest 

{ 

private string _Pol icyReference; 

[DataMember] 

public string Pol i cyReference 

{ 

get { return _Pol i cyReference; } 
set { _Pol icyReference = value; } 
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} 


[DataMember] 

public override RequestType TypeOfRequest 

{ 

get { return RequestType. ViewPol icy; } 

} 

} 

} 


The ViewPolicyResponse class defines the properties shown in Table 6-17. 
Table 6-17 ViewPolicyResponse. cs 


Property 

Purpose 

Policy 

The full policy details referenced by the Pol icy Reference 
passed in the corresponding ViewPolicyRequest. 

TypeOfResponse 

Returns a constant value of ResponseType. ViewPolicy to 
indicate that this is a ViewPolicyResponse. 


Create a new class in the project named ViewPolicyResponse.es with the contents in 
Example 6-38. 

Example 6-38 ViewPolicyResponse.es 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewPolicyResponse : Cl aimsProcessi ngResponse 

{ 

[DataMember] 

public override ResponseType TypeOf Response 

{ 

get { return ResponseType. ViewPolicy; } 

} 


private InsurancePol i cy _Policy; 

[DataMember] 

public InsurancePol icy Policy 

{ 

get { return _Policy; } 
set { _Policy = value; } 

} 

public ViewPol i cyResponse(InsurancePol icy policy) 

{ 

_Pol i cy = pol i cy; 
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} 


} 


Defining the Fault types 

The data contract also specifies what kind of error information is recognized by clients 
consuming the service, which we discuss in more detail in “Defining the Fault types” on 
page 208. 

Create a class named ClaimProcessingFault.es in the project with the content shown in 
Example 6-39. 

Example 6-39 ClaimProcessingFault.es 
using System; 

using System. Col lections. Generic; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 


[DataContract] 

public class ClaimProcessingFault 

{ 

private string _CorrelationId; 
private DateTime _FaultTime; 
private string _ErrorCode; 
private string _Message; 

public ClaimProcessingFaul t(string correlationld) 

{ 

_CorrelationId = correlationld; 

_FaultTime = DateTime. Now; 

} 

[DataMember] 

public string Correlationld 

{ 

get { return _Correl ationld; } 
set { _CorrelationId = value; } 

} 

[DataMember] 

public DateTime FaultTime 

{ 

get { return _FaultTime; } 
set { _FaultTime = value; } 

} 

[DataMember] 

public string ErrorCode 

{ 

get { return _ErrorCode; } 
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set { _ErrorCode = value; } 

} 

[DataMember] 
publ ic string Message 
{ 

get { return _Message; } 
set { _Message = value; } 

} 


} 


} 


The base class ClaimsProcessingFault is used for the majority of application errors in this 
service; however, there is an exceptional case that has its own type of fault. 

When retrieving a list of outstanding claims, it is possible for an exception to be thrown when 
accessing a particular claim record. However callers can still work with the incomplete list. In 
this instance, a special fault type can be used to pass the incomplete list of claims back to the 
client along with a list of the specific faults that occurred. 

Create a new class named ViewOutstandingClaimslncompleteResultsFault.es in the project 
with the content in Example 6-40. 

Example 6-40 ViewOutstandingClaimsIncompleteResultsFault. cs 
using System; 

usi ng System. Col 1 ecti ons .Generi c ; 

using System. Li nq; 

using System. Text; 

using System. Runtime. Serial ization; 

using System. Collections; 

using System.Collections.ObjectModel ; 

namespace Ibm. Broker . Exampl e. Cl aimsProcessi ng 

{ 

[DataContract] 

public class ViewOutstandingClaimsIncompleteResultsFault : 

Cl aimProcessi ngFaul t 

{ 


private Collection<Claim> _Outstandi ngResul ts; 
private Collection<ClaimProcessingFault> _FaultList; 

public ViewOutstandingClaimsIncompleteResultsFaul t(string correlationld) : 
base(correlationld) 

{ 

_Outstandi ngResul ts = new Col 1 ecti on<Claim>() ; 

_FaultList = new Col lection<ClaimProcessingFaul t>() ; 

} 

[DataMember] 

public Col 1 ecti on<Claim> Outstandi ngResul ts 

{ 

get { return _OutstandingResults; } 

} 
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[OnDeserializing] 

private void OnDeserializing(StreamingContext context) 

{ 

_OutstandingResul ts = new Collection<Claim>() ; 

} 

public void AddOutstandingClaim(Claim claim) 

{ 

_Outstandi ngResul ts.Add(cl aim) ; 

} 

[DataMember] 

public Collection<ClaimProcessingFault> FaultList 

{ 

get { return _FaultList; } 

} 

public void AddFault(ClaimProcessingFault fault) 

{ 

_FaultList.Add(fault) ; 

} 


} 


} 


The ViewOutstandingClaimsIncompleteResultsFault is derived from ClaimsProcessingFault 
so that clients who do not want to work with incomplete claims lists can use their normal fault 
handling strategy to cope with the failure. 

Implementing the ICIaimsProcessingWcfService interface 

In this section, you add methods to the ClaimsProcessingWcfService class that implement 
the service contract. The implementation is loosely coupled to the client using the WCF 
service contract; therefore, it is not necessary for a consumer of the service to understand the 
implementation, and indeed the implementation can be replaced without impacting an 
existing client, provided that the semantics of the service contract are retained. 

In this section, you complete the service by implementing the operation contracts. 

Adding required data members 

Recall that the data used by the service is stored in files on the file system. The 
implementation of the service must be able to locate the correct location for these files. To do 
so, add the private data members in Example 6-41 on page 210 to 

ClaimsProcessingWcfService. The code in bold must be added to the class definition outside 
the scope of any of the class methods. 

Example 6-41 Private data members controlling file locations 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

public class ClaimsProcessingWcfService : ICIaimsProcessingWcfService 

{ 

private string BaseDir = "C:\\temp\\testData"; 
private const string CustomersSuffix = "customers"; 
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private const string ClaimsSuffix = "claims"; 
private const string PolicySuffix = "policies"; 


The _BaseDir variable sets the base location for the files created and accessed by the 
service. In this example, the variable is set to the directory c:\temp\testData. This directory 
must exist on the file system before starting the completed service; however, you can alter the 
location to refer to a directory on your local system. 

The constants represent subdirectories for storing particular types of data, for example, 
serialized customer data is stored in C:\temp\testData\customers directory. The customers, 
claims, and policies subdirectories must exist inside your chosen base directory before 
starting the completed service. 


Tip: The \ character is an escape in C#, so to insert a \ character into a string, it needs to 
be preceded by another slash. The @ prefix can be added to string literals so that the 
following string is treated as a verbatim string, ignoring escape characters. The _BaseDir 
declaration can therefore also be written as: 

private string _BaseDir = @”C:\temp\testData” 

The only exception escape sequence that is recognized in verbatim string literals is the 
double quote escape sequence 


Example 6-42 shows private data members representing known insurance policy products 
and partner companies underwriting policies. In a real system, the service might obtain this 
data from a database or from some other means; however, to keep the service simple, the 
data is made available directly to the ClaimsProcessingWcfService class. 

Add the code directly below the code you added in Example 6-41 . The code must be within 
the class definition but outside the scope of any method. 

Example 6-42 Private data members storing example product information 

private enum Pol icyProducts { Bronze, BronzePlus, Silver, Gold, Premium, 
PremiumPlus } 

private enum Underwriters { ItsoInsurancePartnerl, ItsoInsurancePartner2, 
ItsoInsurancePartner3 } 

private static Dictionary<Pol icyProducts, UnderWri ters> 
ProductToProviderMap = new Dictionary<Pol icyProducts, UnderWri ters>() ; 


The ProductToProviderMap dictionary is used to look up which company underwrites a 
particular policy. This is required so that payments are billed to the correct partner company. 
This dictionary must be populated on service startup by adding the code in Example 6-43 on 
page 21 1 to the constructor for ClaimsProcessingWcfService. The variable is declared, so 
the count of the elements in the dictionary is tested before population to prevent duplicate 
content. 

Add the code shown in bold in Example 6-43 to the constructor for the 
ClaimsProcessingWcfService class. 

Example 6-43 Initializing the ProductToProvider map 

publ ic Cl aimsProcessi ngWcfService() 

{ 

CustomerSerial izer = new XmlSerializer(typeof(Customer)) ; 

Pol icySerial izer = new Xml Serial izer(typeof (InsurancePol icy)); 
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ClaimSerial izer = new Xml Seri al izer(typeof (Claim)) ; 


//populate the provider map if not already done 
if (ProductToProviderMap. Count == 0) 

{ 

//predefine the provider to product map 

ProductToProviderMap. Add (Pol icyProducts. Bronze, 

UnderWri ters . ItsoInsurancePartnerl) ; 

ProductToProvi derMap . Add (Pol i cyProducts . BronzePl us , 

UnderWri ters . ItsoInsurancePartnerl) ; 

ProductToProvi derMap . Add (Pol i cyProducts . Si 1 ver , 

UnderWri ters . ItsoInsurancePartner2) ; 

ProductToProvi derMap . Add (Pol i cyProducts . Gol d , 

UnderWri ters . ItsoInsurancePartner2) ; 

ProductToProvi derMap. Add (Pol i cyProducts. Premium, 

UnderWri ters . ItsoInsurancePartner3) ; 

ProductToProvi derMap . Add (Pol i cyProducts . Premi umPl us , 

UnderWri ters . ItsoInsurancePartner3) ; 


} 


This code creates the mapping of policy product names to financial partner names shown in 
Table 6-18. 

Table 6-18 Policy Product Name to Underwriter mapping 


Policy Product Name 

Financial Partner 
underwriting this policy 
product. 

Bronze 

ItsoInsurancePartnerl 

BronzePlus 

ItsoInsurancePartnerl 

Silver 

ltsolnsurancePartner2 

Gold 

ltsolnsurancePartner2 

Premium 

ltsolnsurancePartner3 

PremiumPlus 

ltsolnsurancePartner3 


Generating test data 

To get started with this scenario, you need some test data to work with. Add the method 
shown in Example 6-44 to the ClaimsProcessingWcfService to generate three sample 
customers, a sample policy, and a sample claim. 

Example 6-44 Generating test data 

private void CreateTestDataQ 

{ 

Customer cust = new CustomerQ; 

cust .Customerld = "CUSTOOOOl 11 ; 

cust. Address = "1 Generic Street, Any Town, USA"; 

cust . Fi rstName = "John"; 

cust. Surname = "Doe"; 

cust .OtherNames .Add ("James") ; 

cust .OtherNames .Add ("Jeffrey") ; 

cust . Emai 1 = "johndoeQi tso.exampl e. i bm.com 11 ; 
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Wri teCustomerToFi 1 e(cust, _BaseDir + "\\" + CustomersSuffix) ; 

Customer cust2 = new Customer(); 

cust2.CustomerId = M CUST00002 M ; 

cust2. Address = "1 Generic Street, Any Town, USA"; 

cust2. Fi rstName = "Sam"; 

cust2. Surname = "Doe"; 

cust2.0therNames .Add ("Stephen") ; 

cust2.0therNames .Add ("John") ; 

cust2 . Emai 1 = " samdoeOi tso . exampl e . i bm.com" ; 

Wri teCustomerToFi 1 e(cust2, _BaseDir + "\\" + CustomersSuffix); 

Customer cust3 = new CustomerQ; 

cust3.CustomerId = "CUST00003" ; 

cust3. Address = "1 Generic Street, Any Town, USA"; 

cust3. Fi rstName = "Jane"; 

cust3. Surname = "Doe"; 

cust3.0therNames.Add("Ji 11"); 

cust3.0therNames .Add ("Jenny") ; 

cust3. Emai 1 = "janedoe@i tso. exampl e. i bm.com" ; 

Wri teCustomerToFi 1 e(cust3, _BaseDir + "\\" + CustomersSuffix); 

InsurancePol i cy p = new InsurancePol i cy () ; 
p. Named Parties. Add (cust2) ; 
p. Named Parties. Add (cust3) ; 
p.Pol icyCover = 1000; 
p.Pol icyExcess = 150; 

//add one year 

p.Pol icyExpiryDate = DateTime.Now + new TimeSpan(365, 0, 0, 0, 0); 

p.Pol icyholder = cust; 

p.Pol icyNumber = "P0LICY0001" ; 

p.Pol icyStartDate = DateTime.Now; 

р. Underwri ter = "Partner Insurance Company A"; 

Wri tePol i cyToFi 1 e(p, _BaseDir + "\\" + Pol i cySuffix) ; 

Cl aim c = new Cl aim() ; 

с. Customer = cust3; 

c.ClaimDate = DateTime.Now - new TimeSpan(20, 0, 0, 0, 0); 

c.ClaimRecei vedDate = DateTime.Now; 

c.ClaimReference = "CLAIM0001" ; 

c.ClaimValue = 400; 

c. Pol icyNumber = "P0LICY0001" ; 

c. Description = "Accidental damage to car, no other parties involved"; 
c. Status = Cl aimState.Submi tted; 

Wri teCl aimToFi 1 e(c, _BaseDir + "\\" + Cl aimsSuffix) ; 


} 


This code must be called only when the test data does not already exist. This condition is 
tested for by checking if there are any files present in the customers subdirectory before 
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creating the test data. Add the code shown in Example 6-45 to the constructor for the 
ClaimsProcessingWcfService class. 

Example 6-45 Creating test data if it does not already exist 

//if there is no data present then create some test data 
if (Directory. GetFiles(_BaseDir + "\\" + CustomersSuffix) . Length == 0) 

{ 

CreateTestData() ; 

} 


The completed constructor for ClaimsProcessingWcfService now looks like Example 6-46. 

Example 6-46 The completed constructor for ClaimsProcessingWcfService 

publ ic ClaimsProcessingWcfService() 

{ 

CustomerSerial izer = new Xml Seri al izer(typeof (Customer)) ; 

PolicySerializer = new Xml Serial izer(typeof (InsurancePol i cy) ) ; 

ClaimSerializer = new XmlSerializer(typeof(Claim)); 

//if there is no data present then create some test data 
if (Directory. GetFi 1 es (_BaseDi r + "\\" + CustomersSuffix) . Length == 0) 

{ 

CreateTestData() ; 

} 


//populate the provider map if not already done 
if (ProductToProviderMap. Count == 0) 

{ 

//predefine the provider to product map 
ProductToProviderMap. Add (Pol i cy Products. Bronze, 

Underwriters. ItsoInsurancePartnerl) ; 
ProductToProviderMap. Add (Pol i cy Product s.BronzePl us, 

Underwriters. ItsoInsurancePartnerl) ; 

ProductToProviderMap. Add (Pol i cy Products. Si 1 ver, 

Underwriters. ItsoInsurancePartner2) ; 
ProductToProviderMap. Add (Pol i cy Product s. Gol d, 

Underwriters. ItsoInsurancePartner2) ; 
ProductToProvi derMap . Add (Pol i cy Products . Premi urn. 

Underwriters. ItsoInsurancePartner3) ; 
ProductToProvi derMap .Add (Pol i cy Products . Premi umPl us , 

Underwriters. ItsoInsurancePartner3) ; 


} 


} 


Implementing the ApproveClaim method 

The code for the ApproveClaim method is shown in Example 6-48. 

1 . Add the new using statement shown at the top of the service class to get access to the 
Culture. InvariantCulture class, which is required to tell the system that strings in a fault 
thrown by this class will not be translated. 

Example 6-47 Using statement 

using System. Col lections. ObjectModel ; 
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2. Add this code to the ClaimsProcessingWcfService.es file. 

Example 6-48 The ApproveClaim method 

public Approved aimResponse Approved aim(ApproveCl aimRequest request) 

{ 

Approved aimResponse Response; 
try 
{ 

//First find out if the claim exists 

if (File.Exists(_BaseDir + M \\" + ClaimsSuffix + M \\" + request. Cl aimReference)) 

{ 

Claim Cl aimToApprove = GetClaimFromFile(_BaseDir + "\\" + ClaimsSuffix + "\\" + 
request . Cl ai mReference) ; 

if (request .Val ueApproved > Cl aimToApprove. Cl aimVal ue) 

{ 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFaul t(request.Messageld) ; 

Fault. ErrorCode = "ERROIO"; 

Fault. Message = "Could not approve claim. Reason: Approved value 11 + request .Val ueApproved + 11 is 
higher than total value of claim. 11 ; 

throw new Faul tException<ClaimProcessingFaul t>(Faul t, new Faul tReason(new 
Faul tReasonText ( Fault. Message, Cul turelnfo. Invar iantCul ture)) , new Faul tCode( Faul t. ErrorCode) ) ; 

} 

el se 

{ 

//get the policy associated with this claim 

if (File.Exists(_BaseDir + "\\" + PolicySuffix + "\\" + Cl aimToApprove. Pol icyNumber)) 

{ 

InsurancePol icy Pol icyToCheck = GetPol i cyFromFi 1 e(_BaseDi r + "\\" + PolicySuffix + "\\" + 

Cl aimToApprove. Pol i cyNumber) ; 

i f (Pol icyToCheck. Pol i cyCover > Cl aimToApprove. Cl aimVal ue) 

{ 

//Policy can be approved and a payment generated 

int PaymentValue = Cl aimToApprove. Cl aimVal ue - Pol icyToCheck. Pol icyExcess; 
if (PaymentVal ue < 0) PaymentValue = 0; 

Payment GeneratedPayment = new Payment (); 

GeneratedPayment .Payee = Cl aimToApprove. Customer; 

GeneratedPayment .Amount = PaymentValue; 

GeneratedPayment .Underwri ter = Pol icyToCheck. Underwriter; 

Response = new Approved aimResponse(GeneratedPayment) ; 

Cl aimToApprove. Status = Cl aimState. Approved; 

Cl aimToApprove. Notes += System. Envi ronment.NewLine + 11 [" + DateTime.Now + "] AgentRef: 11 + 
request .AgentReference + 

System. Envi ronment.NewLine + "APPROVED " + request .Val ueApproved; 

Wri teCl aimToFi 1 e(Cl aimToApprove, _BaseDir + "\\" + ClaimsSuffix); 

} 

el se 

{ 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new Cl aimProcessingFaul t(request. Messageld) ; 

Fault. ErrorCode = "ERR012"; 

Faul t. Message = "Could not approve claim. Reason: Policy cover of " + 

Pol icyToCheck. Pol i cyCover + 

" is less than value of claim " + Cl aimToApprove. Cl aimVal ue; 
throw new Faul tException<Cl aimProcessi ngFaul t>(Faul t, new Faul tReason(new 
Faul tReasonText (Fault. Message, Cul turelnfo. Invar iantCul ture)) , new Faul tCode( Faul t. ErrorCode) ) ; 

} 

} 

el se 

{ 
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//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFaul t(request.Messageld) ; 

Fault. ErrorCode = "ERROll"; 

Faul t. Message = "Could not approve claim. Reason: Claim refers to non-existent policy 11 + 
Cl aimToApprove. Pol i cyNumber; 

throw new Faul tException<ClaimProcessingFault>(Fault, new Faul tReason(new 
Faul tReasonText( Faul t. Message, Cul ture Info. Invar iantCul ture)) , new Faul tCode( Faul t. ErrorCode) ) ; 

} 


el se 

{ 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFaul t(request.Messageld) ; 

Fault. ErrorCode = "ERROIO"; 

Faul t. Message = "Could not approve claim. Reason: Claim " + request .Cl aimReference + " does not 
exist."; 

throw new Faul tException<ClaimProcessingFault>(Fault, new Faul tReason(new 
Faul tReasonText( Faul t. Message, Cul turelnfo. InvariantCul ture)) , new Faul tCode( Faul t. ErrorCode) ) ; 


catch (Exception e) 

{ 

//Are we an exception type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

//Return the error to the caller 

Cl aimProcessi ngFaul t Fault = new ClaimProcessingFault(request.Messageld) ; 

Fault. ErrorCode = "ERR009"; 

Faul t. Message = "Could not approve claim. Reason: " + e. Message; 
throw new Faul tExcepti on<Cl aimProcessi ngFaul t>(Faul t, new Faul tReason(new 
Faul tReasonText( Faul t. Message, Cul turelnfo. InvariantCul ture)) , new Faul tCode( Faul t. ErrorCode) ) ; 
} 

el se 

{ 

throw; 

} 

} 

Response. Correl ationld = request .Messageld; 
return Response; 


The ApproveClaim method performs a number of checks before changing the referenced 
claims to the ClaimState.Approved status. The claim and its associated policy must exist in 
the system, and the value of the claim must not exceed the total policy cover. If these 
conditions are met, a new payment is generated for the value of the claim minus the value of 
any excess associated with the policy, and the claim is moved to the Approved state. A note is 
added to the claim to indicate the date that the claim was approved and which agent 
approved the claim. 

If the result of any of the checks is false, a fault is thrown that contains a unique error code 
relating to the error state and an explanation of the root cause of the fault. For example, if the 
claim does not exist on the file system, the fault in Example 6-49 is thrown. 

Example 6-49 A fault indicating that the referenced claim did not exist 
//Return the error to the caller 

ClaimProcessingFault Fault = new Cl aimProcessi ngFaul t (request .Messageld) ; 

Fault. ErrorCode = "ERROIO"; 
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Faul t. Message = "Could not approve claim. Reason: Claim " + 
request. ClaimReference + " does not exist."; 
throw new FaultException<ClaimProcessingFault>(Fault, new Faul tReason (new 
Faul tReasonText (Faul t. Message, Cul turelnfo. InvariantCul ture)) , new 
Faul tCode(Faul t .ErrorCode)) ; 


As shown in Example 6-50, the whole method is wrapped in a try block so that any exception 
types that are known to be generated by the code in the method can be converted into a fault 
that can be consumed by the client. In this case, the code can cause an lOException, if there 
are problems with the underlying file system operations or InvalidOperationException, if an 
attempt is made to write to a FileStream that was opened for reading. These exception types 
are therefore caught and handled by creating a new ClaimsProcessingFault to return to the 
client. Any unexpected Exceptions are rethrown. More detail about exception handling in 
WCF is in Chapter 7, “Scenario: Integrating Windows Communication Foundation in message 
flows - Part 2” on page 273. 

Example 6-50 Converting exceptions into Faults 

catch (Exception e) 

( 

//Are we an exception type we can't handle 

if (e is InvalidOperationException || e is lOException) 

( 

//Return the error to the caller 

ClaimProcessingFault Fault = new ClaimProcessingFault(request.Messageld) ; 
Fault. ErrorCode = "ERR009"; 

Fault. Message = "Could not approve claim. Reason: " + e. Message; 
throw new FaultException<ClaimProcessingFault>(Fault, 

new FaultReason(new FaultReasonText(Fault. Message, 

Culturelnfo. InvariantCul ture) ) , new FaultCode(Fault. ErrorCode)) ; 

} 

el se 

( 

throw; 

} 

} 


Implementing the CreateClaim method 

The CreateClaim method is responsible for taking the details sent in the client request and 
converting these to a Claim object that is stored on the file system on the server that hosts the 
ClaimsProcessingWcfService. 

Add the method shown in Example 6-51 on page 217 to ClaimsProcessingWcfService.es. 
Example 6-51 The CreateClaim method 

public NewCl aimResponse Created aim(NewCl aimRequest request) 

( 

NewCl aimResponse Response; 
try 
( 

//check that the claim is in a submitted state 

if (! request .NewCl aim. Status. Equal s (Cl aimState.Submi tted) ) 

( 

ClaimProcessingFault Fault = new 

Cl aimProcessi ngFaul t (request. Messageld) ; 
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Fault. ErrorCode = M ERR003 M ; 

Faul t. Message = "Could not generate new claim. Reason: 11 + 

"Invalid Claim Status " + request. NewClaim. Status; 
throw new FaultException<ClaimProcessingFaul t>(Faul t, 

new Faul tReason (new Faul tReasonText(Fault. Message, 
Culturelnfo.InvariantCulture)) , new Faul tCode(Fault. ErrorCode)) ; 

} 

//Check if this claim has a claimld 

el se i f (Stri ng. IsNul lOrEmpty (request .NewCl aim. Cl aimReference)) 

{ 

//generate a new claim reference by listing the file 
String NewClaimRef = "CLAIM" + Guid.NewGuid() .ToString("N") ; 
request. NewClaim. Cl aimReference = NewClaimRef; 

WriteClaimToFile(request. NewClaim, _BaseDir + "\\" + Cl aimsSuffix) ; 
Response = new NewCl aimResponse() ; 

} 

el se 

{ 

//If the claim already exists we must return an error 
if (Fi 1 e. Exi sts (_BaseDi r + "\\" + ClaimsSuffix + "\\" + 

request .NewCl aim. Cl aimReference) ) 

{ 

Cl aimProcessi ngFaul t Fault = new 

Cl aimProcessi ngFaul t (request. Messageld) ; 
Fault. ErrorCode = "ERR002"; 

Faul t. Message = "Could not generate new claim. Reason: " + 

"Duplicate claim reference " + request. NewClaim. ClaimReference; 
throw new FaultException<ClaimProcessingFault>(Faul t, new 
Faul tReason (new Faul tReasonText (Faul t. Message, 
Culturelnfo.InvariantCulture)) , new Faul tCode(Fault. ErrorCode)) ; 

} 

el se 

{ 

WriteClaimToFile(request. NewClaim, _BaseDir + "\\" + ClaimsSuffix); 
Response = new NewCl aimResponse() ; 

} 

} 

} 

catch(Exception e) 

{ 

//Are we an exceptin type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

//Return the error to the caller 

Cl aimProcessi ngFaul t Fault = new Cl aimProcessi ngFaul t (request .Messageld) ; 
Fault. ErrorCode = "ERROOl"; 

Faul t. Message = "Could not generate new claim. Reason: " + e. Message; 
throw new FaultException<ClaimProcessingFaul t>(Faul t, 

new Faul tReason (new Faul tReasonText(Faul t. Message, 
Culturelnfo.InvariantCulture)) , new Faul tCode(Fault. ErrorCode)) ; 

} 

el se 

{ 

throw; 

} 
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} 

//set the correl Id 

Response. Correl ationld = request. Messageld; 
return Response; 


This method checks that the claim to be created is in the Submitted state and does not 
already exist before creating a corresponding object on the file system of the server running 
the WCF service. If a claim reference is not already provided, one is generated using the Guid 
class, which generates a 128-bit integer that has a low probability of being duplicated. 


Tip: In this example, the Guid created by the Guid.NewGuid() is converted to a string using 
the toString(“N”) method invocation. This invocation passes “N” as a format specifier, which 
produces a 32-digit numeric string representation of the GUID. The following other format 
specifiers are supported: 

► “D”, 32 digits with hyphens separating groups 

► “B”, As “D” above but enclosed in braces 

► “P”, As “D” above but enclosed in parenthesis 

► “X”, Grouped hexadecimal representation 


Implementing the CreatePolicy method 

The CreatePolicy method also creates customers if the policy contains information about 
customers that are not already known to the system. To do this it uses a helper method. 

Start by adding the method CreateCustomerlfNotExists in Example 6-52 to the class 
definition for ClaimProcessingWcfService. 

Example 6-52 The CreateCustomerlfNotExists method 

private void CreateCustomerlfNotExists (Customer customerToCreate) 

{ 

if (customerToCreate. Customerld == null 

|| customerToCreate. Customerld. Length == 0) 

( 

//Generate a new customer reference 

String NewCustomerRef = "CUST" + Guid.NewGuid() .ToString("N") ; 
customerToCreate. Customerld = NewCustomerRef; 

} 

if ( ! Fi 1 e . Exi sts (_BaseDi r + "\\" + CustomersSuffix + "\\" + 

customerToCreate. Customer Id)) 

( 

Wri teCustomerToFi 1 e(customerToCreate, _BaseDir + "\\" + CustomersSuffix); 

} 

el se 

( 

//check if the names match 

Customer exi sti ngCustomer = GetCustomerFromFile(_BaseDir + "\\" + 

CustomersSuffix + "\\" + customerToCreate. Customerld) ; 
if ( ! exi sti ngCustomer . Equal s (customerToCreate) ) 

( 

//if so resave to update any address info 

Wri teCustomerToFi 1 e(customerToCreate, _BaseDir + "\\" + CustomersSuffix); 

} 
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} 


else 

{ 

throw new IOException("Dupl icate customer ID 

} 


11 + 

customerToCreate.Customerld) ; 


The CreateCustomerlfNotExists method checks if a customer file with a matching ID exists on 
the file system, and if so, uses the Customer.Equals() method discussed on page 175 to 
determine if the customer passed in is the same as a customer found on the file system. An 
lOException is thrown if the customer is passed in with the same ID as an existing customer, 
but the details do not match the existing customer held on file. This lOException is caught by 
the CreatePolicy method and converted into a ClaimsProcessingFault to pass the error cause 
back to the client consuming the service. 

Next, add the CreatePolicyResponse method, shown in Example 6-53. 

Example 6-53 CreatePolicyResponse 

public CreatePolicyResponse CreatePol i cy (CreatePol i cyRequest request) 

{ 

CreatePolicyResponse Response; 
try 
{ 

//check if the policy name matches a known product 
i f (Enum. IsDefi ned(typeof (Pol i cy Products) , request . Pol i cyName)) 

{ 

Pol i cyProducts Product = (Pol i cyProducts) Enum. Parse(typeof (Pol i cyProducts) , request. Pol i cyName); 
//check if customers exist and create them if not 
try 
{ 

CreateCustomerlfNotExi sts (request . PrimaryCustomer) ; 
foreach (Customer NamedParty in request. NamedParties) 

{ 

CreateCustomerlfNotExi sts (NamedParty) ; 

} 

//generate a new policy reference 

String NewPolicyRef = "POLICY" + Guid.NewGuid() .ToStri ng("N") ; 

//Create the pol i cy 

InsurancePol i cy NewPolicy = new InsurancePol i cy () ; 
foreach (Customer NamedParty in request. NamedParties) 

{ 

NewPol icy.AddNamedParty (NamedParty) ; 

} 

NewPolicy. Pol icyCover = request . Pol i cyCover; 

NewPolicy. Pol icyExcess = request. Pol icyExcess; 

NewPolicy. Pol i cyExpi ryDate = request. RequestDate + new TimeSpan(365, 0,0,0); 

NewPol icy. Policyholder = request. PrimaryCustomer; 

NewPol icy. Poli cyName = request. Pol i cyName; 

NewPolicy. Pol icyNumber = NewPolicyRef; 

NewPolicy. Pol icyStartDate = request. RequestDate; 

NewPol icy. Underwriter = ProductToProviderMap[Product] .ToStringO ; 
WritePolicyToFile(NewPolicy, _BaseDir + "\\" + Pol i cySuffix) ; 

Response = new CreatePol i cyResponse(NewPol i cy) ; 


220 Using WebSphere Message Broker V8 in Mid-Market Environments 




} 

catch (Exception e) 

{ 

//Are we an exceptin type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

//Return the error to the caller 

ClaimProcessingFaul t Fault = new ClaimProcessingFaul t (request. Messageld) ; 

Fault. ErrorCode = "ERR020"; 

Faul t. Message = "Could not generate new policy. Reason: Problem creating 
customers: " + e. Message; 

throw new Faul tException<ClaimProcessingFaul t>(Faul t, new Faul tReason (new 
Faul tReasonText (Fault. Message, Cul turelnfo. InvariantCul ture)) , new Faul tCode( Fault. ErrorCode)) ; 
} 

el se 

{ 

throw; 

} 

} 

} 

el se 

{ 

//Return the error to the caller 

ClaimProcessingFaul t Fault = new Cl aimProcessi ngFaul t (request. Messageld) ; 

Fault. ErrorCode = "ERR019"; 

Faul t. Message = "Could not generate new policy. Reason: Unknown Policy name " + 
request. PolicyName; 

throw new Faul tException<ClaimProcessingFaul t>(Faul t, new Faul tReason(new 
Faul tReasonText (Fault. Message, Cul turelnfo. InvariantCul ture)) , new Faul tCode( Fault. ErrorCode)) ; 
} 


} 

catch (Exception e) 

{ 

//Are we an exceptin type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

Cl aimProcessi ngFaul t Fault = new ClaimProcessingFaul t(request. Messageld) ; 

Fault. ErrorCode = "ERR018"; 

Faul t. Message = "Could not generate new policy. Reason: " + e. Message; 
throw new Faul tExcepti on<Cl aimProcessi ngFaul t> ( Faul t, new Faul tReason (new 
Faul tReasonText (Fault. Message, Cul turelnfo. InvariantCul ture)) , new Faul tCode( Fault. ErrorCode)) ; 
} 

el se 

{ 

throw; 

} 

} 

//set the correl Id 

Response. Correlation^ = request .Messageld; 
return Response; 
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Implementing the RejectClaim method 

The RejectClaim method is used by an agent to move a claim to the Rejected state. Unlike 
the ApproveClaim method, no payment information is generated for rejected claims although 
the agent must provide a reason for rejecting the claim, which is logged in to the claims Notes 
property. 

Add the code shown in Example 6-54 to the ClaimsProcessingWcfService class definition. 
Example 6-54 The RejectClaim method 

public RejectCl aimResponse RejectCl aim(RejectCl aimRequest request) 

{ 

RejectClaimResponse Response; 
try 
{ 

//First find out if the claim exists 

if (Fi 1 e. Exi sts (_BaseDi r + H \\" + ClaimsSuffix + "\\" + 

request .Cl ai mReference) ) 

{ 

Claim ClaimToReject = GetCl aimFromFi 1 e(_BaseDi r + "\\" + ClaimsSuffix + "\\" 

+ request. Cl aimReference) ; 

if (ClaimToReject. Status == ClaimState. Submitted) 

{ 

ClaimToReject. Status = ClaimState. Rejected; 

Cl aimToReject. Notes += System. Envi ronment .NewLi ne + "[" + DateTime.Now + 

"] AgentRef: 11 + request .AgentReference + 
System. Environment. NewLine + "REJECTED: 11 + request. Reason; 
WriteClaimToFile(ClaimToReject, _BaseDir + "\\" + ClaimsSuffix); 

Response = new RejectCl aimResponse() ; 

} 

el se 

{ 

//Return the error to the caller 

ClaimProcessingFault Fault = new Cl aimProcessi ngFaul t (request .Messageld) ; 
Fault. ErrorCode = "ERR015"; 

Fault. Message = "Could not reject claim. Reason: " + 

"Claim already had status of " + Cl aimToReject .Status; 
throw new FaultException<ClaimProcessingFault>(Fault, 

new Faul tReason(new FaultReasonText(Fault. Message, 

Cul turelnfo. Invari antCul ture) ) , new Faul tCode (Faul t. ErrorCode)) ; 

} 

} 

el se 

{ 

//Return the error to the caller 

ClaimProcessingFault Fault = new Cl aimProcessi ngFaul t (request .Messageld) ; 
Faul t. ErrorCode = "ERR014"; 

Faul t. Message = "Could not reject claim. Reason: Claim " + 

request. Cl aimReference + " does not exist."; 
throw new FaultException<ClaimProcessingFault>(Fault, 

new Faul tReason (new Faul tReasonText(Fault. Message, 

Cul turelnfo. Invari antCul ture) ) , new Faul tCode (Faul t. ErrorCode)) ; 

} 

} 

catch (Exception e) 

{ 
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//Are we an exceptin type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFault(request.Messageld) ; 
Fault. ErrorCode = "ERR013"; 

Fault. Message = "Could not reject claim. Reason: " + e. Message; 
throw new FaultException<ClaimProcessingFault>(Fault, 

new FaultReason(new FaultReasonText(Fault. Message, 
Culturelnfo.InvariantCulture)) , new FaultCode(Fault. ErrorCode)) ; 

} 

el se 

{ 

throw; 

} 

} 

Response. Correlation^ = request. Messageld; 
return Response; 


Like the ApproveClaim method, the ClaimReference in the incoming request is used to check 
if a claim already exists in the system with this ID. If a claim is found, the state is checked to 
ensure that the claim is not already Approved or Rejected. If all of these conditions are met, 
the Claim is moved to the Rejected state and a note is added to the Claim to record the time 
the claim was rejected, the Agent Reference rejecting the claim, and the reason for rejecting 
the claim. Finally the altered claim object is serialized to the file system on the server hosting 
the ClaimsProcessingWcfService. 

Implementing the ViewClaim method 

The ViewClaim method is responsible for returning the details of a claim when passed a 
reference ID in the request. This can be used by agents examining a claim or by a service 
exposed to customers where they might, for example, be able to use a web service to check 
on the status of their own claim. 

Add the ViewClaim method shown in Example 6-55 to the class definition for the 
ClaimsProcessingWcfService. 

Example 6-55 The ViewClaim method 

public ViewClaimResponse ViewClaim(ViewClaimRequest request) 

{ 

ViewClaimResponse Response; 
try 
{ 

//check if the file exists 

if (Fi 1 e. Exi sts (_BaseDi r + "\\" + ClaimsSuffix + "\\" + 

request .Cl aimReference) ) 

{ 

Response = new ViewClaimResponse(GetClaimFromFile(_BaseDir + "\\" + 

ClaimsSuffix + "\\" + request. Cl aimReference)) ; 

} 

el se 

{ 

//Return the error to the caller 

ClaimProcessingFault Fault = new ClaimProcessingFault(request. Messageld) ; 
Fault. ErrorCode = "ERR004"; 
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Faul t. Message = "Could not view claim. Reason: Claim 11 + 

request .Cl aimReference + 11 does not exist."; 
throw new FaultException<ClaimProcessingFaul t>(Faul t, 

new Faul tReason (new Faul tReasonText(Fault. Message, 

Cul turelnfo. Invari antCul ture) ) , new Faul tCode(Faul t . ErrorCode)) ; 

} 

} 

catch (Exception e) 

{ 

//Are we an exceptin type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

//Return the error to the caller 

Cl aimProcessi ngFaul t Fault = new Cl aimProcessi ngFaul t (request .Messageld) ; 
Fault. ErrorCode = "ERR005"; 

Faul t. Message = "Could not view claim. Reason: " + e. Message; 
throw new Faul tException<ClaimProcessingFaul t>(Faul t, 

new Faul tReason(new Faul tReasonText(Faul t. Message, 
Culturelnfo.InvariantCul ture)) , new Faul tCode(Fault. ErrorCode)) ; 

} 

el se 

{ 

throw; 

} 

} 

Response. Correlation^ = request .Messageld; 
return Response; 


This method is simple with most of the work being performed by the four lines shown in 
Example 6-56. The method checks that the Claim corresponding to the reference on the 
request object exists, and if so, returns the claim using the ViewClaimResponse(Claim) 
constructor. The majority of the code in this method is used to provide meaningful error 
messages to clients consuming the service if an error condition exists. 


Example 6-56 Checking the Claim exists and returning it in a ViewClaimResponse object 

if (Fi 1 e. Exi sts (_BaseDi r + "\\" + ClaimsSuffix + "\\" + request. ClaimReference)) 

{ 


} 


Response = new ViewClaimResponse(GetClaimFromFile(_BaseDir + "\\" + 

ClaimsSuffix + "\\" + request. Cl aimReference)) ; 


Implementing the ViewOutstandingClaims method 

The ViewOutstandingClaims method is used by agents to retrieve details for all claims that 
are in the Submitted state. The agent can then work on a claim and use the appropriate 
methods to accept or reject the claim. This method might be used by a remote application to 
construct a queue of claims awaiting an agent’s attention. 

Create a new method in the ClaimsProcessingWcfService class with the code shown in 
Example 6-57. 

Example 6-57 The ViewOutstandingClaimsmethod 

publ ic ViewOutstandingClaimsResponse 

Vi ewOutstandi ngCl aims (Vi ewOutstandi ngCl aimsRequest request) 
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{ 


Vi ewOut standi ngCl aims Response Response; 
try 
{ 

Col lection<Claim> OutstandingClaims = new Collection<Claim>() ; 
ViewOutstandingClaimsIncompleteResultsFault Fault = null; 

//Iterate over files in the directory 

string[] FilePaths = Directory. GetFiles(_BaseDir + "\\" + ClaimsSuffix, 

"CLAIM*" , SearchOption.TopDi rectoryOnly) ; 

foreach(string File in FilePaths) 

{ 

try 

{ 

Claim Claim = GetClaimFromFile(File) ; 
i f (Cl aim. Status == Cl aimState.Submi tted) 

{ 

if (Fault == null) 

{ 

Out standi ngCl aims .Add (Cl ai m) ; 

} 

el se 

{ 

//if we are faulting add to the fault instead 
Faul t .AddOutstandi ngCl aim (Cl aim) ; 

} 

} 

} 

catch (Exception ei) 

{ 

//Are we an exceptin type we can't handle 

if (ei is Inval idOperationException || ei is IOException) 

{ 

if (Fault == null) 

{ 

//create a new fault 
Fault = new 

Vi ewOutstandi ngCl aims I ncompleteResul ts Faul t (request. Messageld) ; 

//copy the results into the fault 
foreach(Claim Claim in OutstandingClaims) 

{ 

Faul t. AddOutstandi ngCl aim (Cl aim) ; 

} 

} 

Cl aimProcessi ngFaul t InnerFault = new 

Cl aimProcessi ngFaul t (request. Messageld) ; 
InnerFault. Correlation^ = request .Messageld; 

InnerFaul t. ErrorCode = "ERR006" ; 

InnerFaul t. Message = "Error reading claim file " + File + 

" Reason: " + ei. Message; 

Faul t. Add Faul t (InnerFaul t) ; 

} 

el se 

{ 
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throw; 


} 

} 

} 

if (Fault != null) 

{ 

Fault. ErrorCode = "ERR007"; 

Faul t. Message = "There were errors reading claim files, results may" + 

"be incomplete. See remaining FaultList for details."; 
throw new Faul t Except i on<Vi ewOutstandi ngCl aimsIncompleteResul tsFaul t>( 
Fault, new FaultReason(new FaultReasonText(Fault. Message, 
Culturelnfo.InvariantCulture)) , new FaultCode(Fault. ErrorCode)) ; 

} 

else 

{ 

Response = new Vi ewOutstandi ngCl aimsResponse(Outstandi ngCl aims) ; 

} 

} 

catch (Exception e) 

{ 

//Are we an exceptin type we can't handle 

if (e is Inval idOperationException || e is IOException) 

{ 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFault(request.Messageld) ; 
Fault. ErrorCode = "ERR008"; 

Faul t. Message = "Could not generate new claim. Reason: " + e. Message; 
throw new FaultException<ClaimProcessingFault>(Fault, 

new FaultReason(new FaultReasonText(Fault. Message, 
Culturelnfo.InvariantCulture)) , new FaultCode(Fault. ErrorCode)) ; 

} 

el se 

( 

throw; 

} 

} 

Response. Correl ationld = request. Messageld; 
return Response; 


This method has reasonably complex business logic. The purpose of the method is to return 
all Claim objects that exist on the WCF service’s file system that are in the Submitted state. 
This is performed by using the Directory.GetFiles() method to obtain a list of all Claim objects 
and then iterating over these to build up a list of those that have the correct Claim. Status. 

The complication is that reading any of the serialized Claim objects from the file system can 
potentially throw an exception. In the ViewClaim method, if an exception is encountered while 
reading the specific claim that is being requested, there is no way for the method to continue 
and generate a meaningful result and so a fault is returned to the client. In the case of the 
ViewOutstandingClaims method, however, an exception reading one file cannot prevent other 
serialized Claim objects from being successfully read and processed. 

The service itself has no way of knowing if the client can tolerate an incomplete list of 
outstanding claims. An application using this interface on an agent’s computer might tolerate 
the failure because the agent can work on claims other than the one that encountered a 
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problem. On the other hand, a central administration application using the same interface 
might need to know when there is a problem with the serialized data stored on the problem. 


For this reason, the decision to tolerate an incomplete list of data is delegated to the client 
and a new fault type ViewOutstandingClaimsincompleteResultsFault is introduced to return 
the list of Claim objects that were successfully read from the file system along with a list of the 
errors experienced during the operation. This fault type was defined in Example 6-40 on 
page 209. 

If no exceptions are encountered while reading the claims on the file system, a 
ViewOutstandingClaimsResponse object is returned containing the complete list of 
outstanding claims. 

Implementing the ViewPolicy method 

The ViewPolicy method is almost identical to the ViewClaim method except that instead of 
operating on Claim objects this method operates on Policy objects. As such, this method is 
responsible for returning the full details of the policy referenced in the request. 

Add the method definition shown in Example 6-58 to the class definition for 
ClaimsProcessingWcfService. 

Example 6-58 The ViewPolicy method 

public ViewPolicyResponse ViewPol icy(ViewPol icyRequest request) 

{ 

ViewPolicyResponse Response; 
try 
{ 

//check if the file exists 

if (Fi 1 e. Exi sts (_BaseDi r + "\\" + PolicySuffix + "\\" + 

request . Pol i cyReference) ) 

{ 

Response = new ViewPolicyResponse(GetPolicyFromFile(_BaseDir + "\\" + 

PolicySuffix + "\\" + request. Pol i cyReference) ) ; 

} 

el se 

{ 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFault(request.Messageld) ; 
Fault. ErrorCode = "ERR017"; 

Fault. Message = "Could not view policy. Reason: Policy " + 

request. Pol i cyReference + " does not exist."; 
throw new FaultException<ClaimProcessingFault>(Fault, 

new FaultReason(new FaultReasonText(Fault. Message, 
Culturelnfo.InvariantCulture)) , new FaultCode(Fault. ErrorCode)) ; 

} 

} 

catch (Exception e) 

( 

//Are we an exceptin type we can't handle 

if (e is InvalidOperationException || e is IOException) 

( 

//Return the error to the caller 

Cl aimProcessingFaul t Fault = new ClaimProcessingFault(request.Messageld) ; 
Fault. ErrorCode = "ERR016"; 

Fault. Message = "Could not view Policy. Reason: " + e. Message; 
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throw new FaultException<ClaimProcessingFault>(Fault, 

new FaultReason(new FaultReasonText(Fault. Message, 

Culturelnfo. InvariantCul ture) ) , new FaultCode(Fault.ErrorCode)) ; 

} 

el se 

{ 

throw; 

} 

} 

Response. Correl ationld = request. Messageld; 
return Response; 


Verifying the complete ClaimsProcessingWcfService class 

The WCF Service is now complete. You can verify that all the required data members and 

methods are implemented using the Class View in Visual Studio: 

1 . Select Class View from the tab panel at the bottom of the Solution Explorer. If you do not 
see this tab, select View Class View. 

2. From the tree view, expand the Ibm.Broker.Example.ClaimsProcessing namespace node. 

3. Select the ClaimsProcessingWcfService node. 

4. Verify that all of the elements in the members list shown in Figure 6-8 on page 229 are 
present in your completed file. The order of these elements might be different in your 
solution; however, all of the methods and data members must be present. 
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Figure 6-8 ClaimsProcessingWcf Service class view 


6.3.7 Building the WCF Service 

To build the completed WCF service: 

1 . Save all the files in the solution by selecting the File -» SaveAll menu command. 

2. Select the Build -> Build Solution menu item, or click the F7 key. 

3. Check that the build succeeded by examining the build output in the Output panel. A 
successful build looks similar to the output shown in Figure 6-9 on page 230. 
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Output 

Show output from: Build -| | -j | .frl :^ | =% | 

- Build started: Project: ClaimsProcessingWcfServi.ee, Configuration: Debug Any CPU 

Build started 23/63/2012 15:24:19. 

ResolveAssemblyReferences : 

A TargetFramework profile exclusion list will be generated. 

GenerateTargetFrameworkMonikerAttribute: 

Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files. 

_CopyAppConfigFile : 

Skipping target "_CopyAppConfigFile" because all output files are up-to-date with respect to the input files. 

CopyFilesToOutputDirectory : 

ClaimsProcessingWcf Service - > C : \MessageBrokerClaimsProcessor\WcfService\ClaimsProcessingWcf Service\ClaimsProcessingWcf Service\bin\Debug\ClaimsProcessingWcfService .dll 
Build succeeded. 

Time Elapsed 00:00:00.01 

========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ========== 


Figure 6-9 A successful build 

4. Check the output folder listed in the build output. The following files are generated: 

- ClaimsProcessingWcfService.dll 

- ClaimsProcessingWcfService.dll.config 

- ClaimsProcessingWcfService.pdb 


6.3.8 Configuring the WCF service 

In the previous section, you created a WCF service that provides a service contract that 
encapsulates a number of actions that can be invoked on the service by remote clients. You 
provided a file system-based implementation of this service contract in the 
ClaimsProcessingWcfService class. 

When you implemented the service, you did not need to specify any of the specifics about 
where the service is located or what transport is being used. The WCF exposes these 
choices as configuration options that are only resolved at runtime. This effectively decouples 
the transport layer from the application layer, meaning that the application developer 
implementing a WCF service does not need to know how the service will be deployed in 
production. Similarly systems administrators can configure at runtime which endpoints and 
transports are used by the service without needing to rebuild the application. 

The configuration information is held in the App.config file in the Solution. At build time this file 
is copied to a file named after its associated assembly with the .config extension. For 
example, when you built the service in section 6.3.8, “Configuring the WCF service” on 
page 230, the generated assembly produced was called ClaimsProcessingWcfService.dll, 
and the App.config file was copied to ClaimsProcessingWcfService.dll. config. 

In this section, you modify the App.Config file directly because when the service is launched 
from within Visual Studio the file is automatically copied from App.Config to 
ClaimsProcessingWcfService.dll.config. If the WCF Service is hosted externally, modify the 
ClaimsProcessingWcfService.dll.config file directly. 

The contents of the default App.config file 

The New Project Wizard for a WCF Service library creates an App.Config file that already has 
some configuration completed. The App.Config created is displayed in Example 6-59. 

Example 6-59 The automatically generated App. Config file 

<?xml version= l, 1.0 M encodi ng= l, utf-8 M ?> 

<configuration> 

<system.web> 

compilation debug= l, true M /> 
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</system.web> 

<!-- When deploying the service library project, the content of the config file 
must be added to the host's 

app. config file. System. Configuration does not support config files for 
libraries. --> 

<system . servi ceModel > 

<servi ces> 

<servi ce 

name=" I bm. Broker. Example. Cl aims Process ing. I Cl aims Process ingWcf Servi ce. Cl aims Proces 
si ngWcfServi ce"> 

<endpoint address=" " binding =l, wsHttpBinding" 
contract=" I bm. Broker. Exampl e.Cl aims Proces si ng. I Cl aims Process i ngWcfServi ce. I Cl aimsP 
rocessi ngWcfServi ce"> 

<identity> 

<dns val ue="local host" /> 

</identity> 

</endpoint> 

<endpoint address =l, mex" binding="mexHttpBinding" 
contract=" IMetadataExchange" /> 

<host> 

<baseAddresses> 

<add 

baseAddress="http://l ocal host : 8732/Des i gn_T i me_Addresses/Cl aims Proces si ngWcfServi c 
e/Servi cel/" /> 

</baseAddresses> 

</host> 

</servi ce> 

</services> 

<behaviors> 

<serviceBehaviors> 

<behavior> 

<!-- To avoid disclosing metadata information, 

set the value below to false and remove the metadata endpoint above 
before deployment --> 

<servi ceMetadata httpGetEnabl ed="True l 7> 

<!-- To receive exception details in faults for debugging purposes, 
set the value below to true. Set to false before deployment 
to avoid disclosing exception information --> 

<serviceDebug includeExceptionDetail InFaul ts="False" /> 

</behavior> 

</servi ceBehavi ors> 

</behaviors> 

</system. servi ceModel > 

</configuration> 


The configuration related to WCF is contained in the <system.ServiceModel> xml element. 
The <services> element contains specifications for all of the WCF services that are 
configured using this App.config file. It is possible for a single application to host more than 
one WCF service, for example. 

Each service is defined by a <service> element within the <services> node, and each service 
consists of a name, an optional behaviourConfiguration attribute, and a set of endpoints. The 
behaviorConfiguration attribute can be used to refer to a behavior in the <serviceBehaviors> 
element. This can be useful when a WCF-provided behavior, such as Metadata Exchange 
(MEX), is desired on some services but not on others. 
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Each <endpoint> element specifies an address that the service exposes a service contract 
on, the name of the service contract to invoke when receiving requests at this address, and 
the binding to use. Addresses are relative to any defined-base addresses, so in 
Example 6-60, the MEX endpoint is set to: 

http: //local host:8732/Design_Time_Addresses/Cl aims Process i ngWcfServi ce/Servi cel/me 
x 

The main service is exposed on the following endpoint: 

http: //local host :8732/Design_Time_Addresses/Cl aims Process i ngWcfServi ce/Servi cel/ 

Example 6-60 Service definition showing mex endpoint 
<servi ce 

name=" Ibm. Broker. Exampl e.Cl aimsProcessi ng. I Cl aimsProcessi ngWcfServi ce.Cl aimsProces 
si ngWcfServi ce"> 

<endpoint address= IMI bi ndi ng="wsHttpBi ndi ng" 
contract= 11 Ibm. Broker. Exampl e.Cl aimsProcessi ng. I Cl aimsProcessi ngWcfServi ce. I Cl aimsP 
rocessi ngWcfServi ce"> 

<identity> 

<dns value= l, localhost M /> 

</identity> 

</endpoint> 

<endpoint address="mex 11 binding= l, mexHttpBinding M contract =l TMetadataExchange M 

/> 

<host> 

<baseAddresses> 

<add 

baseAddress="http://l ocal host :8732/Design_Time_Addresses/Cl aimsProcessi ngWcfServi c 
e/Servicel/ M /> 

</baseAddresses> 

</host> 

</service> 


The MEX behavior is covered in more depth in section 6.4, “Obtaining information about the 
service using MEX” on page 246. 

Setting an appropriate base address 

The base address generated by default is long and unwieldy. In this example, we set the base 
address to http: //local host : 8732/Cl aimsProcessi ngWcfServi ce/ by replacing the content 
of the <host> xml element in App.Config with the address definition shown in Example 6-61 . 

Example 6-61 Setting the base address for this service 
<baseAddresses> 

<add baseAddress="http://l ocal host : 8732/Cl aimsProcessi ngWcfServi ce/" /> 
</baseAddresses> 


Removing the WSHttpBinding endpoint 

For this example, we use a NetTcpBinding to expose the service through TCP/IP rather than 
the default web service based binding. The endpoint with a wsHttpBinding must therefore be 
removed by deleting the endpoint definition shown in Example 6-62 on page 233 from your 
App.Config file. 


232 


Using WebSphere Message Broker V8 in Mid-Market Environments 



Example 6-62 Removing the endpoint using a wsHttpBinding 


<endpoint address = M 11 bi ndi ng="wsHttpBi ndi ng" 

contract=" I bm. Broker. Exampl e.Cl aimsProcessi ng. I Cl aims Process i ngWcfServi ce. I Cl aimsP 
rocessi ngWcfServi ce"> 

<identity> 

<dns value= l, localhost M /> 

</identity> 

</endpoint> 


Adding a NetTcpBinding 

In this example, you configure WCF to use a TCP/IP-based protocol for communication 
between the client and the service. The WCF framework provides a suitable binding called 
NetTcpBinding for this purpose. The NetTcpBinding is suitable for communication between 
different machines over an existing tcp network and has the advantage of having a lighter 
serialization and deserialization cost than the WebServices-based bindings. This makes 
NetTcpBinding a good choice when performance is a key consideration. 

To configure the NetTcp binding several key pieces of information are required: 

► The endpoint address that the service is configured to use. For the NetTcpBinding, this 
consists of the following key components: 

- The net.tcp:// URI prefix, which indicates that this is a NetTcp address. 

- The host name of the service or IP address to bind to. In this instance, you will use 
localhost. 

- The service to use for listening to connections. In this case, you will use 8523. 

- Optionally a subpath indicating that this endpoint definition is only to be used for 
requests to some subset of the URI space at this address. In this example, you are not 
setting a path because only one service contract will be exposed to the client. 

Tip: One use for setting a subpath for an endpoint is so that multiple services can 
listen on the same port. This is possible by enabling the Net.Tcp port sharing 
feature. More details about port sharing is at: 

http://msdn.mi crosoft .com/en-us/1 i brary/ms734772.aspx 

► A name for the binding, which is used when the binding configuration must be referred to 
in other parts of the App.Config file. 

► The fully-qualified name of the service contract exposed by this endpoint. In this example, 
the contract is Ibm.Broker.Example.ClaimsProcessing.lClaimsProcessingWcfService. 

To add a NetTcp endpoint listening on port 8523 on localhost, add the endpoint definition 
shown in Example 6-63 to the <services> element under the <system.serviceModel> tag. 

Example 6-63 A NetTcpBindings endpoint definition 

<endpoi nt address="net. tcp: //local host : 8523" bi ndi ng="netTcpBi ndi ng" 
bi ndi ngConfiguration="" name="TcpIpEndPoi nt" 
contract=" Ibm. Broker . Exampl e. Cl aimsProcessi ng. I Cl aimsProcessi ngWcfServi ce" /> 


For this example, the default configuration of the NetTcpBindings is used, so the 
bindingConfiguration attribute is blank. If however the default configuration is not sufficient, 
the binding can be configured by providing a value for the bindingConfiguration attribute. 
When set, this attribute refers to a <binding> element with the same name. This <binding> 
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element can be used to hold additional configuration options and must be placed under the 
system. ServiceModel/bindings/netTcpBinding xml node. For example, to configure the 
endpoint to only select a single connection at a time, the <bindings> element shown in 
Example 6-64 is created. To enable this on the TcpIpEndPoint, set the bindingConfiguration 
attribute to singleConnectionBinding. 

Example 6-64 Configuring a binding for maxConnections = 1 

<bindings> 

<netTcpBi ndi ng> 

<binding name= l, singleConnectionBinding M maxConnections= l, r 1 /> 
</netTcpBinding> 

</bi ndi ngs> 


Some common options supported by the NetTcpBindings are shown in Table 6-1 9. For the 
complete list of supported options and additional documentation, see: 

http://msdn.mi crosoft .com/en-us/1 i brary/system.servi cemodel .nettcpbi ndi ng_properti 
es.aspx 


Table 6-19 Common NetTcpBinding properties 


Property 

Description 

MaxConnections 

The maximum number of accepted connections that can be 
queued awaiting dispatch on the server. 

SendTimeout 

The length of time that the server will wait for a write operation 
to the socket to complete before raising an exception. 

ReceiveTimeout 

The length of time that the server will wait for a read operation 
to the socket to complete before raising an exception. 

ListenBacklog 

The maximum number of connection requests that can be 
queued by the listener. 

MaxReceivedMessageSize 

The maximum size of message that this binding will accept. 


Using the WCF Service Configuration Editor to configure the WCF 
Service 

Microsoft Visual Studio includes a tool for configuring WCF services. You can use this tool to 
modify the WCF settings in the App.Config file: 

1 . Select Tools WCF Service Configuration Editor from the menu. 

2. After the WCF Service Configuration Editor loads, select File Open -» Config File from 
the menu. 

3. Use the Open dialog to navigate to the App.Config file that is associated with your project, 
and click Open. 

The WCF Service Configuration editor will load your App.Config file and display it. 

4. Navigate to Services -» 

Ibm.Broker.Example.ClaimsProcessing.ClaimsProcessingWcfService -» 

EndPoints -» TcpIpEndPoint. 

You will see the configuration associated with this endpoint displayed in the editor as 
shown in Figure 6-10 on page 235. 
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Figure 6-10 Viewing the TcpipEndPoint in the WCF Service Configuration Editor 

You can make changes to the configuration editor, which are reflected in the project’s 
App.Config file when you save the file. 

6.3.9 Testing the WCF Service using the WCF Test Client 

Visual Studio provides a tool that can read the service contract of a WCF service and allow 
the user to invoke service operations by populating fields in a graphical tool. This tool is called 
the WCF Test Client and is launched automatically when you run the WCF Service from 
within Visual Studio. 

To test the WCF Service: 

1 . Ensure that the _BaseDir\customers directory is empty (_BaseDir was defined in the 
example code as c:\temp\testData, so if you have not changed the path, ensure 
c:\temp\testData\customers is empty). This makes sure that the service will generate the 
example data when it starts. If you do not clear the directory, you can still use the WCF 
Test Client to test the service; however, the results from some of the operations can vary. 

2. Select Debug -» Start without Debugging from the Visual Studio menu. 


Administrator privileges might be required: Depending on your version of windows 
and your user configuration, you might need to log on as Administrator or start Visual 
Studio with elevated privileges using the Run as Admin right-click context menu 
option. 


Visual Studio automatically hosts the WCF Service for you. An information bubble is briefly 
displayed in the system tray to indicate this, as shown in Figure 6-1 1 on page 236. 
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^ 

4 V WcfSvcHost 

Your serviced) have been hosted. 

Click here to view detailed information. 

Figure 6-11 Visual Studio automatically hosts your WCF Service when you run the project 

3. The WCF Test Client also automatically launches. The WCF Test Client generates the list 
of known operations using the MEX endpoint. You will see that there is a Service node 
corresponding to this services mex URI. Fully expanding this node of the tree shows all of 
the operations defined by this service, as shown in Figure 6-12. 



Figure 6-12 The WCF Test Client 

4. To test the CreatePolicy operation: 

a. Double-click the CreatePolicy operation. 

b. Fill in the value of each field in the Request panel. 

Selecting a field that corresponds to one of the defined datatypes allows you to select 
the appropriate type from a drop-down menu. For example, in the Value Column for the 
PrimaryCustomer field, clicking the box allows you to select the Customer datatype, 
which is then expanded to allow you to populate the fields appropriate to that datatype. 

Fields that take a list or collection start off with the value length=0, which refers to the 
number of objects in the collection. Altering this to read length=1 , for example, causes 
the WCF Client to automatically generate space to input a single object. 

Your completed CreatePolicy Request panel now looks like the example in Figure 6-13 
on page 237. 
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Figure 6-13 Testing the CreatePoiicy Operation 

c. Click the Invoke button. 

The request is sent to the WCF service, and the response is displayed in the Response 
panel, as shown in figure Figure 6-14 on page 238. 
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FI {return} 


Ibm . Broker. Example .Claims Processing .Create Polic 


Policy 


Ibm . Broker. Example .Claims Processing . Insurance P 


E 

3 Named Parties 

length=1 

Ibm . Broker. Example .Claims Processing .CustomerO 



Q [01 


Ibm . Broker. Example .Claims Processing .Customer 



Address 

”1 Example Road, Fictional Town, USA," 

System. String 



;■■■■ Customerld 

"CUST265033c4dc334c7abf 3e03bd1 1ffce07' System. String 



Email 

"jennyjanesmith @itso .example .ibm .com " 

System. String 



First Name 

"Jenny" 

System. String 



0 OtherNames 

length=1 

System .String 0 



1 [0] 

"Jane"' 

System. String 



L - Surname 

"Smith" 

System. String 



PolicyCover 

6000' 

System. Int32 



Policy Excess 

160 

System. Int32 



Policy Expiry Date 

27/03/2013 03:24:00 

System. DateTime 



Policy Name 

"Bronze Plus" 

System. String 



Policy Number 

" PO LIC Y6S2422a4 Babc4e40aS6c6aa 1 341f ec System .String 



Policy Start Date 

27/03/2012 09:24 :0O 

System. DateTime 


- 

3 Policyholder 


Ibm . Broker. Example .Claims Processing .Customer 



Address 

"1 Example Road, Fictional Town, USA," 

System .String 



Customerld 

"C UST02c7Sa€0dS61 42f 03eb406dcf 398c7aB System .String 



Email 

"johnjamessmith @itso .example .ibm .com" 

System. String 



First Name 

"John" 

System. String 



0 - OtherNames 

length =1 

System. String 0 



[0] 

"James" 

System. String 



Surname 

'"Smith" 

System .String 



Underwriter 

"Itso Insurance Partnerl " 

System. String 


Correlation Id 

"MSG001" 

System. String 


ResponseTime 

27/03/2012 03:36:33 

System. DateTime 


TypeOf Response 

CreatePolicy 

Ibm . Broker. Example .□aims Processing . ResponseT 


Figure 6-14 The response from the CreatePolicy Operation 


Tip: The TypeOfRequest was initially set incorrectly in the dialog box because in WCF the 
constructors for objects are not run when serialization / deserialization takes place. 
Because the field does not access a member variable but rather returns a constant for 
each class of request it is actually possible to successfully make the request even if the 
TypeOfRequest field is set incorrectly in the WCF Test Client. 


Because the CustomerlDs for the two customers created were left null, new IDs were 
generated for them by the system. Similarly a new ID was generated for the policy 
itself. 

5. To test the CreateClaim: 

d. In the WCF Test Client, double-click the CreateClaim operation. A new tab is created in 
the right panel for this operation. 

e. Fill in the Request Panel, as shown in Figure 6-15 on page 239. 
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B request 

Ibm . Broker. Example .Claims Processing . Newdai Ibm . Broker. Example .Claims Processing . NewClaim R 


-J NewClaim 

Ibm . Broker. Example .Claims Processing .Claim 

Ibm . Broker. Example .Claims Processing .Claim 



Claim Date 

22/03/2012 12:21 :00 

System. DateTime 



Claim Received Date 

27/03/201 2 09:47 

System. DateTime 



Claim Reference 

(null) 

System. String 



ClaimValue 

200 

System. Int32 


G 

Customer 

Ibm . Broker. Example .Claims Processing .Custome Ibm . Broker. Example .Claims Processing .Customer 



Address 

1 Generic Street, Any Town, USA 

System. String 



Customerld 

CUST00001 

System. String 



Email 

johndoe @itso .example .ibm .com 

System. String 



First Name 

John 

System. String 



0 - OtherNames 

length=2 

System. String D 



j HO] 

James 

System. String 



HI 

Jeffrey 

System. String 



Surname 

Doe 

System. String 



Description 

Windscreen chipped while driving on the highvi System .String 



Notes 

(null) 

System .String 



Policy Number 

POLICYOOOI 

System. String 



Status 

Submitted 

Ibm . Broker. Example .Claims Processing .ClaimState 


Application Id 

WCF Test Client 

System. String 


Message Id 

MSG0O2 

System. String 


RequestDate 

27/03/201 2 09:46 

System. DateTime 


TypeOf Request 

NewClaim 

Ibm . Broker. Example .Claims Processing . Request Tyj 


Figure 6-15 CreateClaim Request 


f. Click the Invoke button. 

The response is displayed in the Response panel, as shown in Figure 6-16. 


B (return) 


Ibm . Broker. Example .Claims Processing . NewClaim 1 

| Correlation Id 

"MSG0O2" 

System .String 

ResponseTime 

27/03/2012 09:52:1 1 

System. DateTime 

TypeOf Response 

NewClaim 

Ibm . Broker. Example .Claims Processing . Response' 


Figure 6-16 Create Claim Response 


Tip: If you make a mistake supplying the data, it is possible for the Proxy object to enter the 
Faulted state. If this happens, select the Start a new proxy check box before invoking the 
operation again. 


6. The newly created claim refers to an already existing policy POLICYOOOI . To view this 
policy, test the ViewPolicy operation by following these steps: 

a. Select the ViewPolicy operation. 

b. Fill in the request panel, as shown in Figure 6-17. 


B request Ibm. Broker. Example .Claims Processing.' View Pt Ibm. Broker. Example .Claims Processing .View Policy 

j ■ Policy Reference PQUCYOOOI System .String 

; ■ Application Id WCF Test Client System .String 

j ■ Message Id MSG003 System .String 

;■ Request Date 27/03/201209:53 System. DateTime 

TypeOf Request View Policy Ibm . Broker. Example .Claims Processing . Request^ 

Figure 6-17 ViewPolicy Request 


c. Click the Invoke button. The WCF Service will return the response shown in 
Figure 6-18 on page 240. 
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Id (return) 



Ibm . Broker. Example .Claims Processing .View Policy 

£ 

Policy 


Ibm . Broker. Example .Claims Processing . Insurance 1 


E 

-_} Named Parties 

length=2 

Ibm . Broker. Example .Claims Processing .CustomerD 



0 - [0] 


Ibm . Broker. Example Claims Processing Customer 



0-IU 


Ibm . Broker. Example Claims Processing Customer 



PolicyCover 

1030 

System. Int 32 



Policy Excess 

iso 

System. Int 32 



Policy Expiry Date 

27/03/2013 09:34:00 

System . DateTime 



PolicyName 

(null) 

NullObject 



PolicyNumber 

" POLICY™!" 

System .String 



PolicyStartDate 

27/D3/2D12 09:34:00 

System. DateTime 


- 

E: Policyholder 


Ibm . Broker. Example Claims Processing Customer 




Address 

”1 Generic Street, Any Town, USA" 

System .String 




Customerld 

"CUSTOODOI" 

System .String 




Email 

"johndoe @itso .example .ibm .com " 

System .String 




First Name 

"John" 

System .String 



G 

p OtherNames 

length=2 

System .String D 




Surname 

"Doe" 

System .String 



Underwriter 

"Partner Insurance Company A" 

System .String 


Correlation Id 

"MSG0O3" 

System .String 


ResponseTime 

27/03/2012 10:40:23 

System . DateTime 


TypeOf Response 

ViewPolicy 

Ibm . Broker. Example Claims Processing . Response' 


Figure 6-18 ViewPolicy Response 


7. There are now two claims in the system. To view the predefined claim, CLAIM0001 , follow 
these steps: 

a. Double-click the ViewClaim Operation 

b. Fill in the request parameters, as shown in Figure 6-1 9. Note that we are passing in the 
claim reference CLAIM0001. 


0 request 

Ibm . Broker. Example Claims Processing . ViewG Ibm . Broker. Example Claims Processing .' ViewClaim 

□aim Reference 

CLAJM0001 

System .String 

.Application Id 

WCF Test Client 

System .String 

Message Id 

MSG004 

System .String 

Request Date 

27/03/2012 10:47 

System . DateTime 

TypeOf Request 

ViewClaim 

Ibm. Broker. Example Claims Processing. Requests 


Figure 6-1 9 ViewClaim Request 


c. Click the Invoke button. The WCF Service will return the response shown in 
Figure 6-20 on page 241 . 
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Id (return) 



Ibm . Broker. Example .Claims Processing . Vlewdaim 

0 Claim 



Ibm . Broker. Example .Claims Processing .□aim 

!■■■■ Claim Date 

07/03/201203:34:00 

System. DateTime 

Claim Received Date 

27/03/2012 09:34:00 

System. DateTime 

□aim Reference 

"CLAIMOOOT" 

System .String 

□aim Value 

400 

System. Int32 

0- Customer 


Ibm . Broker. Example .Claims Processing .Customer 


Address 

”1 Generic Street, Any Town, USA" 

System .String 


Customerld 

"CUST00003" 

System .String 


Email 

"janedoe @itso .example .ibm .com” 

System .String 


First Name 

”Jane" 

System .String 

G 

B OtherNames 

length=2 

System .String D 


Surname 

"Doe"' 

System .String 

Description 

"'Accidental damage to car, no other parties 

ir System .String 

Notes 

(null) 

NullObject 

PolicyNumber 

"POLICYOOOI" 

System .String 

Status 

Submitted 

Ibm . Broker. Example .Claims Processing .daimState 

| Correlation Id 

"MSG004" 

System .String 

ResponseTime 

27/03/2012 10:47:25 

System. DateTime 

TypeOf Response 

ViewQaim 

Ibm . Broker. Example .Claims Processing . Response' 


Figure 6-20 ViewClaim Response 


8. All outstanding claims in the system can be viewed using the ViewOutstandingClaims 
operation. You can use this operation to determine the ClaimReference’s of these claims 
so that we can use the ApproveClaim operation on one of the claims and the RejectClaim 
operation on the other. To run the ViewOutstandingClaims operation: 

a. Double-click the ViewOutstandingClaims operation. 

b. Fill in the Request panel, as shown in Figure 6-21 . 


0 request 

Ibm . Broker. Example .Claims Processing ASewOi Ibm . Broker. Example .daims Processing . ViewOutst; 

.Application Id 

WCF Test Client 

System .String 

Message Id 

MSG0O5 

System .String 

Request Date 

27/03/2012 10:53 

System . DateTime 

TypeOf Request 

ViewOutstandingClaims 

Ibm . Broker. Example .Claims Processing . Request Ti 


Figure 6-21 ViewOutstandingClaims Request 


c. Click the Invoke button. The WCF Service will return the response shown in Figure a 
on page 242. 
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0 (return) 


Ibm . Broker. Example .Claims Processing .Vi 

3 OutstandingClaims 

length=2 

Ibm . Broker. Example .Claims Processing .□ 

1 Q- [0] 


Ibm . Broker. Example .Claims Processing .□ 

□aimDate 

07/03/2012 09:34:00 

System. DateTime 

□aim Received Date 

27/03/2012 09:34:00 

System. DateTime 

ClaimReference 

'■CLftiiuiooor 

System. String 

□aimValue 

m 

System. Int32 

(+) Customer 


Ibm . Broker. Example .Claims Processing .□ 

Description 

" Accidental damage to car, no other parties involved" 

System. String 

!■■ Notes 

(null) 

NullObject 

PolicyNumber 

'■POLICYOOOr 

System. String 

Status 

Submitted 

Ibm . Broker. Example .Claims Processing .□ 

0-[1] 


Ibm . Broker. Example .Claims Processing .□ 

□aimDate 

22/03/2012 12:21 00 

System. DateTime 

Claim Received Date 

27/03/2012 09:47:00 

System. DateTime 

ClaimReference 

"C UK 1 Mf c9Q395741 3b4394324e If 76d 1 b74f bb " 

System. String 

□aimValue 

200 

System. Int32 

© Customer 


Ibm . Broker. Example .Claims Processing .□ 

Description 

"Windscreen chipped while driving on the highway." 

System. String 

Notes 

(null) 

NullObject 

PolicyNumber 

"POLICYOOOI'' 

System. String 

Status 

Submitted 

Ibm . Broker. Example .Claims Processing .□ 

Correlation Id 

"MSG0O5" 

System. String 

j ResponseTime 

27/03/2012 10:56:02 

System. DateTime 

TypeOf Response 

ViewOutstandingClaims 

Ibm . Broker. Example .Claims Processing . R( 


Figure 6-22 ViewOutstandingClaims Response 


d. Take a note of the two ClaimReference values. One of these will be the predefined 
claim CLAIM0001 , but the other one will have a uniquely generated claim reference 
number. In the example shown, this is CLAIMfc933957413b4594824e1f76d1b74fbb; 
however, this will be different on your system. 

9. We will use the ApproveClaim method to approve the predefined claim CLAIM0001 . To 
use the WCT Test Client to execute the ApproveClaim operation follow these steps: 

a. Double-click the ApproveClaim operation in the WCF Test Client. 

b. Fill in the Request panel, as shown in Figure 6-23. 


0 request 

Ibm . Broker. Example .Claims Processing . Appnov Ibm . Broker. Example .Claims Processing .Approved 

Agent Reference 

Agent 001 

System .String 

ClaimReference 

CLAIM0001 

System .String 

ValueApproved 

400 

System. Int32 

.Application Id 

WCF Test Client 

System .String 

Message Id 

MSG006 

System .String 

Request Date 

27/03/201211:00 

System . DateTime 

TypeOf Request 

Approvedaim 

Ibm . Broker. Example .Claims Processing . Request Tj 


Figure 6-23 ApproveClaim Request 


c. Click the Invoke button. The WCF Service generates the response shown in 
Figure 6-24 on page 243. 
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Id (return) 


Ibm . Broker. Example .Claims Processing .Approved 

E 

-J Payment 


Ibm . Broker. Example .Claims Processing . Payment 


!■■■■ Amount 

250 

System. Int32 


0 - Payee 


Ibm . Broker. Example .Claims Processing .Customer 


Address 

"1 Generic Street, .Any Town, USA" 

System .String 


Customerld 

"CUST00003" 

System .String 


Email 

"janedoe @itso .example .ibm .com " 

System .String 


!■■ First Name 

"Jane" 

System .String 


□ OtherNames 

length=2 

System .String D 


! m 

-Jill- 

System .String 


| 1 in 

"Jenny" 

System .String 


Surname 

"Doe" 

System .String 


Underwriter 

"Partner Insurance Company A" 

System .String 


Correlation Id 

"MSGOOO" 

System .String 


ResponseTime 

27/03/2012 11:01:51 

System. DateTime 


TypeOf Response 

ApproveClaim 

Ibm . Broker. Example .Claims Processing . Response' 


Figure 6-24 ApproveClaim Response 


d. The service generated the payment value of 250 by subtracting the value of the excess 
applicable to this policy (150) from the total value of the claim (400). As you can see, 
this means that the service had to refer to the policy referenced by the claim because 
we did not pass in the value for the excess as part of the request. 

e. The service also generated the payment for the correct Underwriter Partner Insurance 
Company A. 

10. Reject the second claim using the RejectClaim operation. Refer to the claim reference 
number. To use the WCF Test Client to invoke the RejectClaim operation: 

a. Double-click the RejectClaim operation. 

b. Fill in the Request Panel, as shown in Figure 6-25. Substitute the claim reference value 
CLAIMfc933957413b4594824e1f76d1b74fbb with the unique value generated on your 
system. 


0 request 

Ibm . Broker. Example .Claims Processing . RejectClaim Re 

Ibm . Broker. Example .Claims Processing . Re 

Agent Reference 

Agent 001 

System. String 

Claim Reference 

C LAI Mfc933S5741 3b4534S24e If 70d 1 b74f bb 

System. String 

! ■ Reason 

Insufficient description of incident. 

System. String 

.Application Id 

WCF Test Client 

System. String 

Message Id 

MSG007 

System. String 

Request Date 

27/03/201211:09 

System. DateTime 

TypeOf Request 

RejectClaim 

Ibm . Broker. Example .Claims Processing . Re 


Figure 6-25 RejectClaim Request 


c. Click the Invoke button. The WCF Service will return the response shown in 
Figure 6-26. 


0 (return) 


Ibm . Broker. Example .Claims Processing . RejectClaii 

Correlation Id 

■'MSG007' 

System .String 

ResponseTime 

27/03/201 2 1 1 : 1 0:53 

System . DateTime 

TypeOf Response 

RejectClaim 

Ibm . Broker. Example .Claims Processing . Response' 


Figure 6-26 RejectCtaimResponse 


1 1 .To confirm that the state of the claims was updated, invoke the ViewOutstandingClaims 
operation again by repeating the instruction in step 8 on page 241 . If you do so, you will 
see that the Claims no longer appear in the list of outstanding claims, as shown in 
Figure 6-27 on page 244. 
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G (return) 


Ibrm . Broker. Example .Claims Processing .VlewOutst; 

OutstandingQaims 

length =0 

Ibm . Broker. Example .Claims Processing .Claim □ 

Correlation Id 

(null) 

NullObject 

ResponseTime 

27/03/3012 11:14:50 

System. DateTime 

TypeOf Response 

VlewOutstandingQaims 

Ibm . Broker. Example .Claims Processing . Response' 


Figure 6-27 There are no outstanding claims in the system 


12. You can use the ViewClaim operation on either of these claims by repeating the 
instructions in step 7 on page 240. For example you can see that the Status of 
CLAIM0001 is now approved, as shown in Figure 6-28. 


B (return) 


Ibm . Broker. Example .Claims Processing . ViewQaim 1 

0 Claim 


Ibm . Broker. Example .Claims Processing .□aim 


j Claim Date 

07/03/201 2 09:34:00 

System. DateTime 


□aim Received Date 

27/03/201209:34:00 

System. DateTime 


□aim Reference 

"CLAIMOOOT 1 

System .String 


□aimValue 

400 

System. Int32 


©■■Customer 


Ibm . Broker. Example .Claims Processing .Customer 


Description 

” Accidental damage to car, no other parties in System .String 


Notes 

"\n|[27/03/2012 1 1 :01 :51] .Agent Ref : Agent Of System .String 


PolicyNumber 

"POLICYOOOI " 

System .String 


Status 

.Approved 

Ibm . Broker. Example .Claims Processing .ClaimState 


Correlation Id 

"MSG094" 

System .String 

ResponseTime 

27/03/2012 11:17:30 

System. DateTime 

TypeOf Response 

ViewQaim 

Ibm . Broker. Example .Claims Processing . Response" 


Figure 6-28 CLAIM0001 is now Approved 


13. So far you tested the service for operations that complete successfully. You can test the 
fault behavior of the system by supplying data that generates a ClaimsProcessingFault by 
following these steps: 

a. Double-click the ViewClaim operation. 

b. Fill out the Request panel so that it refers to a claim that does not exist in the system, 
as shown in Figure 6-29. 


0 request 

Ibm . Broker. Example .Claims Processing .VlewO; Ibm . Broker. Example .Qaims Processing .'ViewQaim 1 


□aim Reference 

CLAIM_INVALID_01 

System. String 


.Application Id 

WCF Test Oient 

System. String 


Message Id 

MSG003 

System. String 


RequestDate 

27/03/2012 11:20 

System. DateTime 


TypeOf Request 

ApproveClaim 

Ibm . Broker. Example .□aims Processing . Request Ty 


Figure 6-29 Using the ViewClaim operation on an invalid Claim Reference 


c. Click the Invoke button. 

d. The WCF Client displays an error box to indicate that a Fault occurred. The Error 
Details indicate that the reason for the fault is that the claim does not exist in the 
system, as shown in Figure 6-30 on page 245. 
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Microsoft WCF Test Client 


m 



Failed to invoke the service. Possible causes: The service is offline or inaccessible: the 
client-side configuration does not match the proxy: the existing proxy is invalid. Refer to 
the stack trace for more detail. You can try to recover by starting a new proxy, restoring 
to default configuration, or refreshing the service. 


Emor Details 

Could not view claim. Reason: Claim C LA,I M_l N VALI D_Q 1 does not exist. 


Server stack trace: 

at System .Service Model .Channels .ServiceChannel . Handle Repty{ProxyOperation Runtime operation . 
at System .Service Model. Channels. ServiceChannel .Call{String action. Boolean oneway. PrctxyOperal 
at System .Service Model .Channels .ServiceChannel Proxy . In vokeService{l MethodCall Message methc 
at System .Service Model .Channels .ServiceChannel Proxy . In voke(l Message message] 


- 


Exception rethrown at [0]: 

(<) "" 



Close 


Figure 6-30 A Fault occurred during processing 


The WCF Test Client can be a useful tool for developing a WCF service because it allows 
developers to test and troubleshoot the service without needing to develop a client. The WCF 
Test Client also displays the ABC specification that it is using to communicate with the service 
in the Config File node. You can view this configuration by double-clicking the Config File 
node from the tree on the left of the WCF Test Client, as shown in Figure 6-31 . 


!?§ V/CF Test Client 0 

File Tools Help 

Ei PJ] My Service Projects 

B jfi] http ://localhost :8732/Oaims Processing WcfService/mex 
0 5° IQaimsPnocessingWcfService (Tcp Ip End Point) 

^ CreateQaimO 

!■•••-♦ ViewClaimO 

♦ ViewOutstandingQaimsO 
^ ApproveOaimO 
i RejectOaimO 

!■•••• -♦ ViewPolicyO 
=♦ Create PolicyO 
! ||^ Config File 

ViewOutstandmgClaims Appro veClaim RejectClaim ViewOutstandmgClaims (1) ViewClaim (1) ViewClaim (2) Client. dll. config | 00 

<7xml version ="1.0" encoding="utf-8"?> 

<configuration> 

<system .service Model > 
bindings > 

<netTcp Binding? 

<binding name="TcplpEndPoint" doseTimeout="00:01 :00" open Timeout ="00:01:00" 
receiveTimeout ="00: 10:00" sendTimeout="00:01 :00" transaction Row= , 'false" 
transferMode = " Buff ered ' ' transaction Protocol = ' 'OleT ransactions " 
host NameComparison Mode ="Strong Wildcard " listen Backlog =" 1 0" 
maxBufferPoolSize="524288" max Buff erSize="65536" maxConnections="10" 
max Received Message Size = "65536" > 

<readerQuotas maxDepth=”32" maxStringContentLength="8192" maxArrayLength=" 16384" 
max Bytes PerRead= "4096" maxNameTableCharCount="16384" /> 

<reliableSession ordered = "true" inactivityTimeout="00:10:00" 
enabled= , 'false" /> 
security mode = "Transport"? 

transport clientCredentialType="Windows" protectionLevel="EncryptAndSign" /> 
cmessage dientCredentialType= "Windows" /> 

</security? 

</binding? 

</net Tcp Binding? 

</bindings? 

<dient? 

<endpoint address="net.tcp://1ocalhost:8523/" binding="netTcpBinding" 
bindingConfiguration ="Tcp Ip End Point" contrad =" IQaims Processing Wcf Service" 
name="Tcp Ip EndPoint"? 
identity? 

<userPrindpalName value="DAVICRIGW500\davicrig" /? 

</identity? 

</endpoint? 

</dient? 

</system service Model ? 

^configuration? 




Figure 6-31 Viewing the configuration that was used by the WCF Test Client 


Exit the debug mode by selecting Debug Stop Debugging in the Visual Studio menu. For 
now, leave the service running. 
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6.4 Obtaining information about the service using MEX 


WCF exposes a facility called MetaData Exchange (MEX) that allows ABC information to be 
obtained by querying the service itself. This facility allows clients to automatically generate 
the code required to interact with the WCF service. 

MEX is automatically enabled by the New Project Wizard when the WCF service library is 
created. The endpoint definition shown in Example 6-65 specifies that MEX is active over the 
HTTP transport at the address mex. 

Example 6-65 MEX endpoint definition in App.Config 

<endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" /> 


The address is relative to the base address of the service, shown in the host definition in 
Example 6-66, so the full address of the MEX endpoint is: 

http: //local host : 8732/Cl aimsProcessi ngWcfServi ce/mex 

Example 6-66 Base address definition in App. Config 
<host> 

<baseAddresses> 

<add baseAddress=" http: //local host : 8732/Cl ai msProcessi ngWcfServi ce/" /> 
</baseAddresses> 

</host> 


The IMetadataExchange contract is a service contract implemented by the .NET WCF 
classes. For the metadata exchange to work correctly the service may either implement the 
MetadataReference contract or add the serviceMetadata behavior to the App.config file. The 
New Project Wizard automatically added this behavior, as shown in Example 6-67. 

Example 6-67 The serviceMetadata behavior in App.Config 
<servi ceMetadata httpGetEnabl ed="true"/> 


Navigating to the base address of the application with a web browser returns a web page that 
provides instructions about how to automatically generate a client to call the service, as 
shown in Figure 6-32 on page 247. 

http: //local hos t: 8732/Cl ai msProcessi ngWcfServi ce/ 
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ClaimsProcessingWcfService Service 


You have created a service. 

To test this service, you will need to create a client and use it to call the service. You can do this using the svcutil.exe tool from the 
command line with the following syntax: 

svcutil.exe rttp : //locair.ost : 52/ Cieiir.sFroces3ir.cWcf service/ ?w3di 

This will generate a configuration file and a code file that contains the client class. Add the two files to your client application and use the 
generated client class to call the Service. For example: 

C# 

class Test 
I 

static void Main() 

£ 

ClaimsProcessingWcf ServiceClient client = new ClairasProcessingWcfServiceClient () ; 

// Use the ‘client 1 variable to call operations on the service. 

// Always close the client, 
client . Close ( ) ; 

} 

} 


Visual Basic 

Class Test 

Shared Sub Main() 

Dim client As ClaimsFrocessingWcf ServiceClient = New Claiir.3Proce3singWcf ServiceClient () 
' U3e the 'client 1 variable to call operations on the service. 

' Always close the client, 
client . Close ( ) 

End Sab 
End Class 


Figure 6-32 A MEX enabled WCF service can display client creation instructions at the Base Address 

When MEX is enabled for a WCF service and the httpGetEnabled is set to true, a WSDL 
document describing the endpoint is also published. The address that the WSDL is published 
on is by default equal to the base address plus the ?wsdl suffix. 

For this service the WSDL publication address is: 

http: //local host : 8732/Cl aimsProcessi ngWcfServi ce/?wsdl 

The WSDL document is useful for both generating .NET service to consume this WCF 
service and in the case of web services-based bindings enabling other clients to consume the 
service. Figure 6-33 on page 248 shows the output of the WSDL displayed in a web browser. 


Chapter 6. Scenario: Integration Windows Communication Foundation in message flows - Part 1 247 



<?xml version ="1.0" encoding ="utf- 8" ?> 

- <wsdl:definitions name-'ClaimsProcessingWcfService" targetNamespace-'http:/ /tempuri.org/" 
xmlns :wsdl- 'http:// schemas.xmlsoap.org/wsdl/" 
xmlns: soap -'http:// schemas.xmlsoap.org/wsdl/soap/" 

xmlns:soapenc="http:// schemas.xrnlsoap.org/ soap/ encoding/" xmlns :wsu=" http ://docs.oasis- 
open.org/ wss/ 2004/ 01/ oasis- 20040 1- wss- wssecurity- utility- l.O.xsd" 
xmlns:xsd -'http://www.w3.org/2001/XMLSchema" 

xmlns:soapl2-'http:/ / schemas.xmlsoap.org/wsdl/soapl2/" xmlns: tns-'http:/ /tempuri.org/" 

xmlns :wsa="http:/ / schemas.xmlsoap.org/ws/2004/08/addressing" 

xmlns :wsp=" http://schemas.xmlsoap.org/ws/ 2004/ 09/ policy" 

xmlns :wsap="http:/ / schemas.xmlsoap.org/ ws/ 2004/ 08/ addressing/ policy" 

xmlns :wsaw="http://www.w3.org/ 2006/ 05/ addressing/ wsdl" 

xmlns :msc=" http://schemas.microsoft.com/ws/2005/12/wsdl/ contract" 

xmlns: wsa 10 -'http:/ / www.w3.org/ 2005/ 08/ addressing" 

xmlns :wsx="http://schemas.xmlsQap.0rg/w5/ 2004/ 09/ mex" 

xmlns: wsam -'http://www.w3.org/20Q7/05/addressing/metadata"> 

- <wsp: Policy wsu:Id="TcpIpEndR 0 int_policy"> 

- <wsp: Exactly One > 

- <wsp:All> 

<msb: Binary Encoding 

xmlns :msb="http:/ /schemas. microsoft.com/ws/ 06/ 2004/ mspolicy/netbinaryl" /> 

- <sp:TransportBinding 

xmlns: sp="http:/ / schema5.xmlsoap.org/ws/2005/07/securitypolicy"> 

- <wsp:Policy> 

- <sp:TransportToken> 

- <wsp:Policy> 

- <msf: WindowsTransportSecurity 

xmlns :msf="http://schemas. microsoft.com/ws/ 2006/ 05/framing/ policy" > 

<ms f : P ro te c ti o n Le v e I >E n cry ptAn d S i g n <f m s f : P ro te c ti o n Lev e I > 

</msf: WindowsTransportSecurity > 

</wsp: Policy > 

</.sp :TransportToken > 

- <sp:AlgorithmSuite> 

- <wsp:Policy> 

<sp:Basic2S6 /> 

</wsp: Policy > 

<fsp : AlgorithmSuite > 

- <sp:Layout> 

- <wsp:Policy> 

<sp:Strict /> 

y/uirn w'v. 

< 1 


A 


[>1 


E 


Figure 6-33 A MEX enabled WCF service will respond to ?WSDL requests over http 


Enabling MEX is required to automatically generate WCF clients and to use the WCF test 
client although it can be viewed as a security exposure in a production environment. It is 
therefore common practice to remove the serviceMetadata behavior and mex endpoint 
definitions prior to deployment in a production environment. 


6.5 Generating WCF client code from a MEX enabled WCF 
service 


Visual Studio includes a tool called SVCUtil that can automatically generate the client side of 
a service contract based on the metadata provided by an MEX enabled endpoint. To generate 
client code: 

1 . Ensure that the WCF Service is running. In this case, the service was started during the 
debug exercise in 6.3.9, “Testing the WCF Service using the WCF Test Client” on 
page 235 and is running in Visual Studio. 
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2. Start a new Visual Studio Command prompt by selecting Start Microsoft Visual 
Studio 2010 -» Visual Studio Tools Visual Studio Command Prompt (2010). 

3. Navigate to a location on disk where you want to store the output files using the cd 
command. 

4. Run the svcutil command against the WSDL address of the service, as shown in 
Example 6-68. 

Example 6-68 Running SVC Util against the running WCF service 

svcuti 1 .exe http : //I ocal host: 8732/Cl ai ms Process ingWcfServi ce/?wsdl 


The svcutil command produces two files, ClaimsProcessingWcfService.es and 
output. config. 

The ClaimsProcessingWcfService.es file can be added to .NET projects to allow a client to 
create a proxy object for the service. Opening this file in a text editor will show that the content 
is different from the ClaimsProcessingWcfService.es file used to actually implement the 
service on the server, as shown in the extract in Example 6-69. 

Example 6-69 ClaimsProcessingWcfService.es output from svcutil 

// 

// <auto-generated> 

// This code was generated by a tool. 

// Runtime Version:4. 0.30319. 239 

// 

// Changes to this file may cause incorrect behavior and will be lost if 
// the code is regenerated. 

// </auto-generated> 

// 

namespace Ibm. Broker. Exampl e. Cl aimsProcessi ng 

{ 

usi ng System. Runtime . Seri al i zati on ; 


[System. Di agnosti cs . DebuggerStepThroughAttri bute ()] 

[System. CodeDom.Compi ler. GeneratedCodeAttri bute( 11 System. Runtime. Serial i zati on 11 , 

"4. 0.0.0")] 

[System. Runtime. Serial ization.DataContractAttribute(Name= l, NewClaimRequest M , 
Namespace= 11 http: //schemas. datacontract .org/2004/07/ Ibm. Broker. Exampl e. Cl aimsProces 
sing")] 

public partial class NewCl aimRequest : object, 

System. Runtime. Serial i zati on. IExtensi bleDataObject 

{ 


pri vate System. Runtime . Seri al i zati on . Extensi onDataObj ect 
extensionDataField; 

private string Appl i cati onldFi el d ; 

private string MessageldField; 

private Ibm. Broker. Example. Cl aims Processing. Cl aim NewCl aimFi eld; 
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private System. DateTime RequestDateField; 


publ i c System. Runt i me . Seri al i zati on . Extensi onDataObj ect Extensi onData 

{ 

get 

{ 

return this. extensi onDataFi el d ; 

} 

set 

{ 

this.extensionDataField = value; 

} 


The details contained in this file do not need to be understood by the consumer of the WCF 
service. Instead the consumer creates an object based on this generated class and can to 
use the object exactly as though it was a local object with WCF automatically managing the 
required serialization and deserialization on the wire. Just like a real local object, a developer 
working with a WCF client can use content assist and automatic code completion to examine 
the service contract. 

The svcutil utility also generates an output.config file that contains the endpoint, bindings and 
contract details required to consume the service. Because the svcutil utility ran against 
localhost, the address of the endpoints are relative to localhost. These can be easily edited 
when deploying the application to a remote system without rebuilding. As shown in 
Example 6-70, the svcutil tool also adds default values for transport specific parameters, such 
as TCP/IP based timeouts. 

Example 6-70 Output.config 

<?xml version =ll 1.0" encodi ng="utf-8 l, ?> 

<configuration> 

<system. servi ceModel > 

<bi ndi ngs> 

<netTcpBi ndi ng> 

<binding name =l, TcpIpEndPoi nt" cl oseTimeout="00:01 :00" openTimeout="00:01 :00" 
recei veTimeout= M 00: 10:00" sendTimeout="00:01 :00" transact i onFlow="fal se" 
transferMode= 11 Buffered 11 transaction Protocol ="01 eTransacti ons" 
hostNameCompari sonMode="StrongWi 1 dcard" 1 i stenBackl og=" 10" 
maxBufferPool Si ze= l, 524288" maxBufferSi ze= l, 65536" maxConnecti ons=" 10" 
maxRecei vedMessageSi ze= 11 65536 "> 

<readerQuotas maxDepth="32 M maxStri ngContentLength= l, 8192" maxArrayLength=" 16384" 
maxBytesPerRead= l, 4096 M maxNameTabl eCharCount= l, 16384" /> 

<rel iableSession ordered="true" inacti vi tyTimeout="00: 10:00" 
enabl ed="fal se" /> 

<security mode= l, Transport ll > 

<transport cl ientCredentialType="Windows" protectionLevel= l, EncryptAndSign M /> 
<message cl ientCredentialType= l, Windows M /> 

</security> 

</bi ndi ng> 

</netTcpBi ndi ng> 

</bi ndi ngs> 

<cl ient> 

<endpoi nt address = "net . tcp: //local host : 8523/" bi ndi ng="netTcpBi ndi ng" 

bi ndi ngConfi gurati on="TcpIpEndPoi nt" contract=" I Cl aims Process i ngWcf Servi ce" 
name =l, TcpIpEndPoi nt"> 


250 Using WebSphere Message Broker V8 in Mid-Market Environments 





<identity> 

<userPrinci pal Name value= l, DAVICRIGW500\davicrig" /> 
</identity> 

</endpoi nt> 

</cl ient> 

</system. servi ceModel> 

</configuration> 


We use these two files in Chapter 7, “Scenario: Integrating Windows Communication 
Foundation in message flows - Part 2” on page 273 to build a .NETCompute node that can 
consume the ClaimsProcessingWcfService. 


6.6 WCF hosting options 

One of the advantages of WCF is that the same service can be deployed or hosted in a 
number of different ways without modification. This allows the user to choose the most 
appropriate hosting option for a broad range of tasks. Some hosting options, such as Visual 
Studio's built in host or hosting from a command line application, suit development and test 
activities; whereas, in production environments the resiliency and the uniform administrative 
interfaces of IIS or Windows Services can be leveraged by hosting the service within one of 
these run time environments. In this section, we use the ClaimsProcessingWcfService to 
demonstrate the hosting flexibility provided by WCF. 


6.6.1 Hosting using Visual Studio 

When you use the Debug menu in Visual Studio to launch the ClaimsProcessingWcfService, 
Visual Studio automatically hosts your WCF service for you. Visual Studio continues to host 
your service until the WCF Test Client is closed or until you terminate the application. 

This form of hosting is extremely useful when developing a service because it allows the rapid 
testing of any changes in the test client. It has the downside that Visual Studio must be 
running to host the service. This is clearly not suitable for production deployment but there are 
also instances where hosting with Visual Studio might not be desirable, such as when 
automating the testing of the service. 


6.6.2 Hosting using a stand-alone application 

It is possible to host a WcfService from any stand-alone .NET application, which is achieved 
by instantiating a ServiceHost object passing in the type of the Service Library you created, 
as shown in Example 6-71 . 

Example 6-71 Instantiating a new ServiceHost 

ServiceHost ServiceHost = new Servi ceHost(typeof (ClaimsProcessingWcfService)) 


To create a console based host: 

1 . Start a new instance of Visual Studio. 

2. Create a new project: 

a. Select File -» New -» Project. 

b. Select Visual C# -» Windows from the Installed Templates. 
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c. Select Console Application from the middle panel. 

d. Enter Cl aimsProcessi ngConsol eHost in the Name field. 

e. Enter Cl aimsProcessi ngConsol eHostSoluti on in the Solution name field. 

f. Select a directory on the file system to store your solution in the Location field. 

g. Ensure that the Create directory for solution option is selected. 

The completed New Project Wizard now looks like the example in Figure 6-34. 



Figure 6-34 Creating a new Console Application to host the WCF service 

h. Click OK. 

The New Project Wizard creates a new class called Program in the Program.es file. 

3. Rename the class to ClaimsProcessingConsoleHost and the Program.es implementation 
file to ClaimsProcessingConsoleHost.es. 

4. Save ClaimsProcessingConsoleHost.es. 

5. To have access to the WCF framework and the ClaimsProcessingService, you need to 
add their references to the project: 

a. Right-click the References folder in the Solution Explorer, and select Add Reference. 

b. From the .NET tab select System.ServiceModel, and click the OK button. 

c. Right-click the References folder, and select Add Reference. 

d. From the Browse tab, navigate to the directory on the disk that holds the 
ClaimsProcessingWcfService.dll file from your completed WCF Service, as shown in 
Figure 6-35 on page 253. 
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Figure 6-35 Adding a reference to the ClaimsProcessingWcfService assembly 
e. Click the OK button. 

6. Modify the code for the ClaimsProcessingConsoleHost.es file so that it matches the code 
shown in Example 6-72. 

Example 6- 72 ClaimsProcessingConsoleHost. cs 
using System; 

using System. Col lect ions. Generic; 
using System. Li nq; 
using System. Text; 

using System. Servi ceModel ; 

using System. Servi ceModel .Description; 

usi ng Ibm. Broker. Exampl e. Cl aimsProcessi ng; 

namespace Cl aimsProcessi ngConsol eHost 

{ 

cl ass Cl aimsProcessi ngConsol eHost 

{ 

static void Main(string[] args) 

{ 

Console. WriteLine("Starting console host for 
Cl aimsProcessi ngWcf Servi ce") ; 

//instantiate a ServiceHost 
using (ServiceHost serviceHost = new 
Servi ceHost (typeof (Cl aimsProcessi ngWcfServi ce) ) ) 

{ 

//Open the service so that it start listenign for request 
serviceHost. Open() ; 

//Readline() blocks for input so service will continue tor un until 
//the user presses Enter 
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Consol e.Wri te Li ne(" Accept i ng requests. ") ; 
Consol e.Wri teLine("Press <Enter> to exit.."); 
Consol e. ReadLi ne() ; 

} 

} 

} 

} 


7. The console host needs an App.Config file to configure the ABC specification of the WCF 
host: 

a. Select Project -» Add New Item. 

b. In the Add New Item dialog, select Application Configuration File, and leave the 
default name of App.config set, as shown in Figure 6-36. 



Figure 6-36 Adding the App.config file 

c. Click Add. 

d. Copy the configuration information from the ClaimsProcessingWcfServiceProject’s 
App.Config file into the newly created App.Config file. The completed App.Config file 
will then look like Example 6-73. 

Example 6-73 An App.Config file 

<?xml version="1.0" encodi ng="utf-8" ?> 

<configuration> 

<system.web> 

compilation debug="true" /> 
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</system.web> 

<!-- When deploying the service library project, the content of the config file 
must be added to the host's 

app. config file. System. Configuration does not support config files for libraries. 

- -> 

<system.servi ceModel> 

<bi ndi ngs/> 

<servi ces> 

<servi ce 

name=" Ibm. Broker. Exampl e. Cl aimsProcessi ng .Cl aimsProcessi ngWcfServi ce"> 

<endpoint address= M mex" bi ndi ng="mexHttpBi nding" 
contract=" IMetadataExchange" /> 

<endpoi nt address="net.tcp:// local host : 8523 11 bi ndi ng="netTcpBi nding" 
bi ndi ngConfigurati on=" 11 name="TcpIpEndPoi nt" 
contract= 11 Ibm. Broker. Example. Cl aimsProcessi ng. I Cl aimsProcessi ngWcfServi ce" /> 

<host> 

<baseAddresses> 

<add baseAddress=" http: //local host: 8732/Cl aimsProcessi ngWcfServi ce/" /> 
</baseAddresses> 

</host> 

</servi ce> 

</servi ces> 

<behaviors> 

<servi ceBehavi ors> 

<behavi or> 

<!-- To avoid disclosing metadata information, 

set the value below to false and remove the metadata endpoint above 
before deployment --> 

<servi ceMetadata httpGetEnabl ed="true"/> 

<!-- To receive exception details in faults for debugging purposes, 
set the value below to true. Set to false before deployment 
to avoid disclosing exception information --> 

<serviceDebug includeExceptionDetail InFaul ts="Fal se" /> 

</behavior> 

</servi ceBehavi ors> 

</behavi ors> 

</system. servi ceModel > 

</configuration> 


e. Save the App.Config file. 

8. Launch the Console Application by selecting Debug Start without debugging from the 
Visual Studio menu. 

A new console window opens, as shown in Figure 6-37 on page 256. 
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^ fi le: ///C : / Message B rokerC lai ms P rocessor/Wcf Servi ce/C lai ms P rocessi ngConsoleHostSol Lition/. . . 


X 

Starting console host for ClainsProcessingUcf Service 
Accepting requests. 

Press <Enter> to exit.. 

d 


Figure 6-37 The console host running 


After the console-based host starts, it will continue to run until you click the Enter key. You can 
verify that the service is working by using a browser to navigate the base endpoint address 
http://localhost:8732/ClaimsProcessingWcfService/. If the service is running, you can 
see the service description page, as shown in Figure 6-38. 



Figure 6-38 The service description page 

If you implemented the WebSphere Message Broker flow that consumes the service, you can 
use the provided Message Broker Test Client to invoke operations on the WCF Service. 

When you want to terminate the service, click Enter to close the console window. 

Hosting the service in a stand-alone application is ideal for testing in an automated manner or 
deploying within a development team to prototype and refine the service. However when 


256 Using WebSphere Message Broker V8 in Mid-Market Environments 



deploying to a production environment, there are options that give a greater level of resiliency 
and are easier to administer in an enterprise environment. 


6.6.3 Hosting as a service 

You can host your WCF Service as a Windows service so that it can be managed in the same 
way that you manage your other Windows services. In this case the Windows Service will 
create an instance of the WCF Service that exists for the lifetime of the Windows Service. 

Creating the project 

To create a Solution and Project to host your application: 

1 . Create a new project: 

a. Select File -» New ->• Project from the Visual Studio menu. 

b. From the Installed Templates, select Visual C# -» Windows. 

c. From the list in the center pane, select Windows Service. 

d. In the Name field, enter Cl almsProcessi ngWi ndowsServi ceHost. 

e. In the Location field, enter a location on the file system to store your project. 

f. In the Solution name field, enter Cl aims Processings ndowsServi ceHostSol ution. 

g. Ensure that the Create Directory for solution box is selected. 

h. Click OK. 

The completed New Project dialog now looks like Figure 6-39. 



Figure 6-39 Creating a New Windows Service 
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2. The New Project Wizard creates a Servicel .cs file and a Program.es file. Follow these 
steps to rename these classes to more meaningful names: 

a. Select the Servicel.cs file in the Solution Explorer. Right-click and select Rename. 
Enter ClaimsProcessingHostService.es as the name, and click Enter. A dialog asks 
you if you want to rename all project references to Servicel .cs. Select Yes. 

b. Select Program.es from the Solution Explorer, right-click, and select Rename. Enter 
ClaimsProcessingHostServiceMain.es, and click Enter. A message appears that asks 
if you want to rename all project references to Program. Select Yes. 

3. To reference the ClaimsProcessingWcfService, add a reference to the Assembly. To do 
this, follow these steps: 

a. Right-click the References folder in the Solution Explorer, and select Add Reference. 

b. Click the Browse panel. 

c. Navigate to the output folder where the ClaimsProcessingWcfService.dll assembly is 
located, and select it. 

d. Click OK. 

4. You also need to reference the System. ServiceModel assembly to gain access to the WCF 
APIs used and the System. Configuration. Install assembly to gain access to the API that 
allows you to create an installer for this Windows Service. 

To add a reference to the System.ServiceModel.dll assembly: 

a. Right-click the References folder in the Solution Explorer, and select Add Reference. 

b. In the .NET panel, select System.ServiceModel. 

c. Click OK. 

5. To add a reference to the System. Configuration. Install assembly: 

a. Right-click the References folder in the Solution Explorer, and select Add Reference. 

b. In the .NET panel, select System.Configuration. Install. 

c. Click OK. 

6. To add the code to implement the Windows Service: 

a. Open the ClaimsProcessingHostService.es file by double-clicking it. 

b. Right-click in the service Design pane, and select Properties. In the ServiceName 
field, enter ClaimsProcessingService as the value, and close the properties view. 

c. In the service Design pane dialog, select click here to switch to code view, as shown 
in Figure 6-40. 



Figure 6-40 Switch to code view 

d. Modify the code for the ClaimsProcessingHostService.es so that it matches the code 
shown in Example 6-74. 

Example 6-74 ClaimsProcessingHostService.es 
using System; 
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using System. Col lections. Generic; 

using System. ComponentModel ; 

using System. Data; 

using System. Diagnostics; 

using System. Li nq; 

using System. ServiceProcess; 

using System. Text; 

using System. Servi ceModel ; 

using System. Configuration; 

usi ng Ibm. Broker. Exampl e. Cl aimsProcessi ng; 

namespace Cl aimsProcessi ngWi ndowsServi ceHost 

{ 

public partial class ClaimsProcessingHostService : ServiceBase 

{ 

public Servi ceHost cl aimsProcessi ngHost = null; 
publ i c Cl aimsProcessi ngHostServi ce() 

{ 

Ini tial izeComponent () ; 

} 

protected override void OnStart(string[] args) 


cl aimsProcessi ngHost = new 
Servi ceHost (typeof (Cl aimsProcessi ngWcf Servi ce) ) ; 
claimsProcessingHost.Open() ; 

} 

protected override void OnStopO 

{ 

if (cl aimsProcessi ngHost != null) 

{ 

claimsProcessingHost.Close() ; 

} 

} 

} 

} 


7. 

8 . 

9. 

10 . 


Double-click the ClaimsProcessingHostService.es file to open the design. 

Right-click in the design pane, and select Add Installer. 

Double-click the new Projectlnstaller.es file to open the Projectlnstaller in the design view. 

Select serviceProcessInstallerl. Right-click, and select Properties. Click the 
Categorized button in the Properties view ([if - 


)■ 


1 1 .Set the Account value to Local Servi ce, as shown in Figure 6-41 , and close the Properties 
view. 


Q App.config ProjectInstaller.Designer.es ClaimsProcessingHostService.Designer.es - Properties ▼ 


serviceProcessInstallerl System. - 

dT zl 

'}& serviceProcessInstallerl servicelnstallerl 


□ 

(Name) serviceProcessIm 

GenerateMembe True 
Modifiers Private 

□ 

Account LocalService 

HelpText 

Parent Projectlnstaller 


Figure 6-41 Setting the service to run under the LocalService account 
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12. Save and close the Projectlnstaller.es file. 

13. Add an App.Config file to the project so that the ClaimsProcessingWcfService, created by 
the Windows Service host, knows what end points are required. 

Add the App.Config file by following these steps: 

a. Select Project -» Add New Item from the Visual Studio menu. 

b. In the Add New Item dialog, select Application Configuration File, and leave the 
default name of App.config set, as shown in Figure 6-36 on page 254. 


Add New Item - ClaimsProcessingConsoleHost 

Installed Templates 




□ Visual C# Items 
Code 
Data 
General 
Web 

Windows Forms 
WPF 

Message Broker 

Reporting 

Workflow 


Online Templates 


Sort by: Default 


T- T | r 


User Control 
Component Class 
User Control (WPF) 

'-I About Box 

ADO.NET Entity Data Model 
ADO.NET EntityObject Generator 
ADO.NET Self-Tracking Entity Generator 
I Application Configuration File 
Application Manifest File 
Assembly Information File 
Bitmap File 
JXJ Class Diagram 

0 Class to create a Message Broker message 
Class to filter a Message Broker message 


Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C4 Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 
Visual C# Items 


Tvpe: Visual C£ Items 


Search Installed Templates 


A file for storing application configuration and 
settings values 



Figure 6-42 Adding the App.config file 


c. Click Add. 

d. Copy the configuration information from the ClaimsProcessingWcfServiceProject’s 
App.Config file into the newly created App.Config file. The completed App.Config file 
now looks like Example 6-73 on page 254. 

Example 6-75 An App.Config file 

<?xml ver sion =l T.O" encodi ng="utf-8" ?> 

<confi gurati on> 

<system.web> 

compilation debug="true M /> 

</system.web> 

<!-- When deploying the service library project, the content of the config file 
must be added to the host's 

app.config file. System. Configuration does not support config files for libraries. 

--> 

<system.servi ceModel> 
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<bi ndi ngs/> 

<servi ces> 

<servi ce 

name="Ibm. Broker. Exampl e. Cl aimsProcessi ng .Cl aimsProcessi ngWcfServi ce"> 

<endpoint address="mex" bi ndi ng="mexHttpBi nding" 
contracts" IMetadataExchange" /> 

<endpoi nt address="net.tcp:// local host : 8523 11 bi ndi ng="netTcpBi nding" 
bi ndi ngConfigurati on=" 11 name="TcpIpEndPoi nt" 
contract= 11 Ibm. Broker. Example. Cl aimsProcessi ng. IC1 aimsProcessi ngWcfServi ce" /> 

<host> 

<baseAddresses> 

<add baseAddress=" http: //local host : 8732/Cl aimsProcessi ngWcfServi ce/" /> 
</baseAddresses> 

</host> 

</servi ce> 

</servi ces> 

<behaviors> 

<servi ceBehavi ors> 

<behavi or> 

<!-- To avoid disclosing metadata information, 

set the value below to false and remove the metadata endpoint above before 
deployment --> 

<servi ceMetadata httpGetEnabl ed="true"/> 

<!-- To receive exception details in faults for debugging purposes, 
set the value below to true. Set to false before deployment 
to avoid disclosing exception information --> 

<serviceDebug includeExceptionDetail InFaul ts="Fal se" /> 

</behavior> 

</servi ceBehavi ors> 

</behavi ors> 

</system. servi ceModel > 

</configuration> 


e. Save the App.Config file. 

14. Build the Windows Service using the Build -» Build Solution menu item. Select View 
Output to see the results of the build. Note the name of the directory where the executable 
is stored. 

Installing the service 

Before you can start the service, it must be installed using the install util command 

provided with Visual Studio. 

To install the service: 

1 . Open a new Visual Studio command prompt using Start All Programs Microsoft 
Visual Studio 2010 -» Visual Studio Tools Visual Studio Command Prompt (2010). 

2. Navigate to the directory that the generated executable was placed in using the cd 
command. 

3. Using the dir command you can see an executable generated for your project, as shown 
in Figure 6-43 on page 262. 
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^ Visual Studio Command Prompt (2010) 


-I 

C:\MessageBrokerClaimsProcessor\UcfServ ice\C la ims Process ingUindowsServ iceHost So I 
ut ion\C la ims Process ingUindowsServ iceHost \bin\Debug>dir 
Uolume in drive C has no label. 

Uolume Serial Number is 6023-6 76D 

Directory of C:\MessageBrokerClaimsProcessor\UcfService\ClaimsProcessingUindows 
Serv iceHostSolut ion\ClaimsProcess ingUindowsServ iceHost \bin\Debug 

29/03/2012 16:25 <DIR> 

29/03/2012 16:25 <DIR> 

24/03/2012 11:45 31,232 ClaimsProcessingUcfService.dll 

24/03/2012 11:45 134,656 ClaimsProcessingUcf Service .pdb 

29/03/2012 16:25 7,680 ClaimsProcessingUindowsServiceHost.exe 

29/03/2012 16:25 1,645 ClaimsProcessingUindowsServiceHost .exe .conf J 

sr 

29/03/2012 16:25 24,064 ClaimsProcessingUindowsServiceHost .pdb 

29/03/2012 15:29 11,600 ClaimsProcessingUindowsServiceHost . vshost .e* 

e 

17/03/2010 17:39 490 ClaimsProcessingUindowsServiceHost .vshost .e* 

e .man if est 

7 File <s > 211,367 bytes 

2 Dir<s> 4,652,748,800 bytes free 

C:\MessageBrokerClaimsProcessor\UcfServ ice\C la ims Process ingUindowsServ iceHost So I 
ut ion\C la ims Process ingUindowsServ iceHost\bin\Debug> 

d 

J 

d 


Figure 6-43 Checking the output file exists 


4. Enter the command install util ClaimsProcessingWindowsServiceHost.exe. 
When the installer finishes, you will see the output shown in Figure 6-44. 


OKI Visual Studio Command Prompt (2010) 



Process ingUindowsServ iceHost . InstallLog. 

Committing assembly J C:\MessageBrokerClaimsProcessor\UcfService\ClaimsProcessing 
UindowsServ iceHostSolut ion\Claims Process ingUindowsServ iceHost \bin\Debug\ClaimsPr 
ocess ingUindowsServ iceHost .exe J . 

Affected parameters are: 
logtoconsole = 

logf ile = C:\MessageBrokerClaimsProcessor\UcfService\ClaimsProcessingUindowsS 
erv iceHostSolut ion\ClaimsProcess ingUindowsServ iceHost \bin\Debug\ClaimsProcess ing 
UindowsServ iceHost . InstallLog 

as s e mb ly pat h = C : \Me s s age Br o ke r C la ims Pro c e s s o r \Uc f S e r v ic e \C la ims Pro c e s s in gU in 
dowsServ iceHostSolut ion\C la ims Process ingUindowsServ iceHost \bin\Debug\ClaimsProce 
ssingUindowsServ iceHost .exe 

The Commit phase completed successfully. 

The transacted install has completed. 

C:\MessageBrokerClaimsProcessor\Ucf Serv ice\C la ims Process ingUindowsServ iceHost Sol 
ut ion\C la ims Process ingUindowsServ iceHost\bin\Debug> 

3 

d 


Figure 6-44 The Service is installed successfully 


After the service is installed, it can be managed from the Computer Management console 
in the same way that you manage any other Windows Service. 

Setting the access control list 

Before the service can start, you must set an access control list to permit the service to listen 
on the URL listed in the MEX endpoint. This requires a tool called httpcfg.exe, which is 
shipped by default on server versions of Windows and is available separately for Windows XR 
Visit the following web site: 

http://www.mi crosoft.com/downl oad/en/detai 1 s .aspx?di spl ayl ang=en&i d=18546 
On Windows 7 and Windows Vista, the httpcfg.exe tool is superseded by the netsh tool. 

To configure the HTTP registration permissions: 

1 . Open a new Command Prompt window using the Start ->• All Programs -» 

Accessories -» Command Prompt menu item. 
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2. Navigate to c:\Program Files\Support Tools. 

3. Enter the following command that is appropriate for your system: 

httpcfg.exe set urlacl /u http://+8732/ClaimsProcessingWcfService/ /a 
D: (A; ;GX; ; ;WD) 

Or 

C:\>netsh.exe http add urlacl url=http://+:8732/ClaimsProcessingWcfService/ 
user=\Everyone 

Complete the command with a completion code of zero. 


Note: The ACL definition given in the httpcfe.exe command allows all processes from 
all users to make URL registrations on the 

http://localhost:8732/ClaimsProcessingWcfService URL space. If your local security 
guidelines do not allow you to grant global access to this part of the URL space, check 
with your Windows System Administrator to obtain the correct ACL definition to use in 
the httpcfg.exe command. 


Starting and stopping the service 

Start the service by following these steps: 

1 . Open the Computer Management Console by selecting Start Run, and entering 
compmgmt.msc. 

2. Navigate to Services and Applications -» Services in the explorer pane. 

3. Select ClaimsProcessingService from the right panel. 

4. Right-click and select Start. 

You can verify that the service is running by navigating to the base address of the application, 
http: //local host : 8732/Cl aimsProcessingWcfService/, using a web browser. If the service 
is running successfully, you will see the service description page, as shown in Figure 6-45 on 
page 264. 
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ClaimsProcessingWcfService Service 


A 


You have created a service. 

To test this service, you will need to create a client and use it to call the service. You can do this using the svcutil.exe tool from the 
command line with the following syntax: 


svcutil.exe r.ttic : / /iocalr.Qst : i ^ -32 / Ciain'.sF-Qcessir.cWcf Service / ?w3di 

This will generate a configuration file and a code file that contains the client class. Add the two files to your client application and use 
the generated client class to call the Service. For example: 

C# 

class Te3t 
£ 

static void Main ( ) 

£ 

ClaimsProcessingWcf Service Client client = new ClaimsProcessingWcf ServiceClient ( ) ; 

// Use the 'client 1 variable to call operations on the service. 

// Always close the client, 
client . Close ( ) ; 

> 

} 


Visual Basic 


Figure 6-45 The service description page 


Note: Windows Services reports errors to the Windows Event Log, so if your service fails 
to start, you can look up the cause in the Applications section of the Event Viewer. For 
example, failing to enable the URL registration with httpcfg.exe results in a 
System. ServiceModel.AddressAccessDeniedException being reported to the Event Log. 


The WCF service will continue to run for the lifetime of the Windows service. To stop the 
Windows service and therefore stop the WCF service follow these steps: 

1 . Open the Computer Management Console by selecting Start Run and entering 
compmgmt.msc. 

2. Navigate to Services and Applications Services in the explorer pane. 

3. Select ClaimsProcessingService from the right panel. 

4. Right-click, and select Stop. 

Uninstalling the service 

When you make changes to your Windows Service, uninstall the old service before installing 
the new changed service. To uninstall the old service: 

1 . Open a new Visual Studio command prompt using Start All Programs Microsoft 
Visual Studio 2010 -> Visual Studio Tools Visual Studio Command Prompt (2010). 

2. Navigate to the directory that the generated executable was placed in using the cd 
command. 

3. Enter the command install util /u ClaimsProcessingWindowsServiceHost.exe. 

You will see output saying that the uninstall completed, as shown in Figure 6-46 on 
page 265. 
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m Visual Studio Command Prompt (2010) 


Uninstalling assembly J C:\MessageBr0kerClaimsPr0cess0r\Ucf ServiceSClaimsProcessi ^ 
ngUindousServ iceHostSolut ionSClaimsProcessingUindowsServ iceHost \bin\Debug\Claims — 
ProcessingUindowsServiceHost .exe J . 

Affected parameters are: 
logtoconsole = 

logf ile = C:\MessageBrokerClaimsProcessor\UcfSeryice\ClaimsProcessingUindowsS 
erv iceHostSolut ionSClaimsProcess ingUindousServ iceHost SbinSDebugSClaimsProcess ing 
UindousServ iceHost . InstallLog 

assembly path = C : MlessageBrokerClaimsProcessorMJcf Serv ice\ClaimsProcess ingUin 
dousServ iceHostSolut ionNClaimsProcessingUindowsSeru iceHost\bin\Debug\ClaimsProce 
ssingUindowsServ iceHost .exe 

Removing EventLog source ClaimsProcessingServ ice . 

Service ClaimsProcessingServ ice is being removed from the system... 

Service ClaimsProcess ingServ ice was successfully removed from the system. 

Attempt to stop service ClaimsProcessingService . 


The uninstall has completed. 


C:\MessageBrokerClaimsProcessor\WcfServ ice\ClaimsProcessingWindowsServ iceHost Sol 
ut ion\ClaimsProcessingUindowsServ iceHost \bin\Debug> 



Figure 6-46 Uninstalling the Windows Service 


After the service is uninstalled, it no longer appears in the Computer Management Console, 
and you will no longer be able to navigate to the service description page. 


6.6.4 Hosting in Internet Information Services (IIS) 

Perhaps the most common way to host an enterprise WCF application is to use Microsoft’s 
Internet Information Services (IIS) web server. To complete this section, you need to have IIS 
and ASP.NET installed on your machine. 

If you are using IIS V6, you also need the IIS 6 Metabase and IIS 6 Configuration 
Compatibility features installed. 

Visual Studio can automatically deploy a WCF service to the local IIS instance. To deploy the 
ClaimProcessingWcfService: 

1 . Open the ClaimsProcessingWcfService solution in Visual Studio. 

2. Select Build -» Publish ClaimsProcessingWcfService from the menu. 

3. Select the Browse button next to the Target Location field, as shown in Figure 6-47. 



Figure 6-47 PublishWizardl 
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4. In the Open Web site pane, select Local IIS, and then highlight the Default Web site 
Node, as shown in Figure 6-48. 



Figure 6-48 PublishWizard2 


5. Click the Create New Web Application button (®) in the top-right corner. 


6. In the newly created Web Application node, enter the name Cl aimsProcessing, as shown 
in Figure 6-49 on page 267. 
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Figure 6-49 Publish Wizard 3 

7. Click Open. 

8. Click Publish. The project is rebuilt and deployed to IIS. Successful output is shown in 
Figure 6-50. 


Output T ^ X 

Show output from: Build » | ^ | (5^ | ^ | 

c : \WINDOW5\iHicrosoft . MET\Framew*ork\v4 .0 . 30319\Csc , exe /noconfig /nowarn : 1701 j 1702 /nostdli a 
_C opyAppConfigFile : 

Skipping target "_CopyAppConrigFile" because all output files are up-to-date with respect to 
Copy FilesToOutputD'irectory : 

Copying file from "obj \Debug\ClaimsProcessingWcf Service . dll" to "bin\Debug\ClaimsProcessin 
ClaimsProcessingWcfService -> C : \MessageBrokerClaimsProcessor\Wcf5ervice\ClaimsProcessingW 
Copying file from "obj\Debug\ClaimsProcessingWcfService . pdb" to "bin\Debug\ClaimsProcessin 

a 

Build succeeded. 


Time Elapsed 00:00:01.92 

Publish started: Project: ClaimsProcessingWcfService., Configuration: 

Connecting to http : //localhost/ClaimsProcessing . , , 

Publishing folder /... 

Publishing folder bin... 

= = = = = = = = = = Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ========= = 

========== Publish: 1 succeeded, 0 failed, 0 skipped ========== 


irri— 1 


Debug Any CPU -- 



Figure 6-50 Successful publication output 


The Publish Wizard created two new files in the ClaimsProcessing Web Application. You can 
view these in the Computer Management console by following these steps: 

1 . Open the Computer Management Console by selecting Start -» Run, and entering 
compmgmt.msc. 
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2. Navigate to Services and Applications Internet Information Services Web 
Sites ->• Default Web Site ClaimsProcessing. 

You can see two new files, 

Ibm.Broker.Example.ClaimsProcessing.ClaimsProcessingWcfService.svc and 
Web.Config, as shown in Figure 6-51. 



Figure 6-51 Files created by the publish wizard 


Example 6-76 shows the contents of the 

Ibm.Broker.Example. ClaimsProcessing. ClaimsProcessingWcfService. svc file. 

Example 6- 76 bm. Broker. Example. ClaimsProcessing. ClaimsProcessing WcfService.svc 
<%@ ServiceHost 

Service="Ibm. Broker. Exampl e. Cl aimsProcessi ng.Cl aimsProcessi ngWcfServi ce" %> 


This file tells IIS the class that implements the service defined in the Web.Config file. Note 
that the assembly itself is placed in the bin directory of the Web Application, as shown in 
Figure 6-52 on page 269. 
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Figure 6-52 The assembly is located in the Web Application’s bin directory 

Version 7 of IIS supports non-http bindings; however, previous versions do not, so we must 
modify the Web.Config file to expose an http endpoint. 

Open the Web.Config file and modify the contents to match Example 6-77. 

Example 6-77 Web.Config 

<?xml version =ll 1.0" encodi ng= l, utf-8" ?> 

<configuration> 

<system.web> 

compilation debug= l, true M /> 

</system.web> 

<!-- When deploying the service library project, the content of the config file 
must be added to the host's app. config file. System. Configuration does not support 
config files for libraries. --> 

<system. servi ceModel > 

<bi ndi ngs> 

</bindings> 

<servi ces> 

<servi ce 

name=" I bm. Broker. Exampl e.Cl aimsProcessi ng.Cl aimsProcessi ngWcf Servi ce"> 
endpoint address =l, mex" binding="mexHttpBinding" contract="IMetadataExchange" /> 
<endpoi nt address="/WebServi ces" bi ndi ng="basi cHttpBi ndi ng" 
bi ndi ngConf i gurati on=" 11 
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name="WebServi cesEndpoi nt" 

contract=" I bm. Broker. Exampl e.Cl aimsProcessi ng. I Cl aims Process i ngWcfServi ce" /> 
</servi ce> 

</services> 

<behaviors> 

<serviceBehaviors> 

<behavior> 

<!-- To avoid disclosing metadata information, set the value 
below to false and remove the metadata endpoint above before deployment --> 
<servi ceMetadata httpGetEnabl ed= l, true l, / > 

<!-- To receive exception details in faults for debugging purposes, 
set the value below to true. Set to false before deployment 
to avoid disclosing exception information --> 

<serviceDebug includeExceptionDetail InFaul ts= l, False" /> 

</behavior> 

</servi ceBehavi ors> 

</behaviors> 

</system. servi ceModel > 

</configuration> 


The file is essentially the same as the services App.Config file; however, there is no base 
address for the service. This is because when hosted under IIS the base address from the 
App.Config file is not used; instead, the address is defined by the location of the .svc file 
created by the publish wizard. 

In this example, the WCF service is hosted at: 

http: //local hos t/Cl aims Processing/ I bm. Broker. Exampl e.Cl aims Processing. Cl ai ms Proces 
si ngWcfServi ce. svc 

You can navigate to this address using a web browser. You can see the service description 
web page, as shown in Figure 6-53 on page 271 . 
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ClaimsProcessingWcfService Service 


A 


You have created a service. 


To test this service, you will need to create a client and use it to call the service. You can do this using the svcutil.exe tool from the 
command line with the following syntax: 


svcutil.exe httu : //dav-crlcw5QQ/CIalir.sFrccesstt:c/Ifcm. Broker . I x ancle . C 1 a tn'.s F r ccessi r. c . CleiicsFroce 

This will generate a configuration file and a code file that contains the client class. Add the two files to your client application and use 
the generated client class to call the Service. For example: 

C# 

class Test 
£ 

static void Main ( ) 

£ 

ClaimsProcessingWcfService Client client = new Claims? rocessingWcf Service Client ( ) ; 

// Use the 'client 1 variable to call operations on the service. 

// Always close the client, 
client . Close ( ) ; 

I- 

} 


Visual Basic 

< III! 

Figure 6-53 The service description page 

If instead of the service description page you see an error stating that the service Fai 1 ed to 
access IIS metabase, run the ASP.NET IIS Registration tool, which configures the ASP.Net 
framework for use in IIS. To perform this step: 

1 . Open a new Visual Studio command prompt using Start All Programs -» Microsoft 
Visual Studio 2010 -» Visual Studio Tools -» Visual Studio Command Prompt (2010). 

2. Enter the command aspnet_regi is -i. 

Now that the service is created, it can be invoked from a message flow. Proceed to Chapter 7, 
“Scenario: Integrating Windows Communication Foundation in message flows - Part 2” on 
page 273 to continue this scenario. 
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Scenario: Integrating Windows 
Communication Foundation in 
message flows - Part 2 


In this chapter, we develop, deploy, and test a WebSphere Message Broker application that 
consumes the ClaimsProcessingWcfService developed in Chapter 6, “Scenario: Integration 
Windows Communication Foundation in message flows - Part 1” on page 163. 

The WebSphere Message Broker application uses the .NETCompute node to embed a WCF 
client for the service using a TCP/IP-based transport. The scenario also highlights the 
potential of the .NETCompute node by showing examples for transformation and integration 
with Microsoft Word. 

The scenario also showcases some of the new message modelling and mapping technology 
introduced in WebSphere Message Broker V8 in the form of the DFDL Parser and the new 
Mapping node. 


Additional materials: You can download the WebSphere Message Broker project 
interchange file and the .NET class code for this scenario from the IBM Redbooks 
publication web site. See Appendix A, “Additional material” on page 485 for more 
information. 


© Copyright IBM Corp. 2012. All rights reserved 
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7.1 Scenario overview 


Figure 7-1 shows an overview of the completed scenario. 



The scenario developed in this chapter represents an enterprise application for processing 
insurance claims. Recall from 6.1 , “ClaimsProcessingWcfService overview” on page 164, that 
the ClaimsProcessingWcf service exposes seven operations for processing insurance claims 
through the system: 

► ViewOustandingClaims 

► ViewClaim 

► ApproveClaim 

► RejectClaim 

► CreateClaim 

► CreatePolicy 

► ViewPolicy 

These operations are exposed as WCF services; however, in a heterogeneous environment, 
not all applications can interface directly with WCF. Some applications might be running on 
operating systems other than Microsoft Windows or might use heritage data exchange 
formats that cannot be modified when introducing new functionality to the system. 
WebSphere Message Broker can be used to provide an interface between these heritage 
applications and the WCF service. 

In this scenario, we assume that our fictional insurance company has an existing Enterprise 
Service Bus (ESB) architecture and that components of this ESB exchange data in a 
Canonical Message Format. The ESB is implemented with WebSphere Message Broker. 
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The purpose of the message flow in this scenario is to provide an interface for use by existing 
applications that communicate using MQ messages in a text/binary message format and by 
SOAP-based web service clients. The MQ interface represents multiple internal applications 
used by employees at the insurance company to perform business functions, such as agents 
that must view claims and then approve or reject them. The SOAP interface represents a web 
service that can be exposed to customers, allowing them to check on the status of their claim. 

In addition to providing an interface for the WCF Service, the message flow also provides the 
necessary routing and connectors for additional business logic associated with some of the 
operations in the WCF service. 

To provide a robust and resilient solution, the scenario provides an error handling strategy so 
that the root cause of failures in processing can be communicated back to the originator of 
each request for remedial action. 

The general execution flow for an operation is: 

1 . An input message is received on one of the input nodes for the flow. 

2. The input message is transformed into a Canonical Message Format that is suitable for 
transmission across other ESB services. 

3. A WCF request is made to the ClaimsProcessingWcfService using TCP/IP. The WCF 
service executes the operation. 

4. Any additional processing required for this operation is performed. 

5. A reply message is sent to the originator of the request with the results from the operation. 

The CreatePolicy and ApproveClaim operations both require additional processing: 

CreatePolicy When a new policy is created, a word document containing a policy 

confirmation letter is generated. This letter is emailed to the 
customer’s email address and is also written to the local file system so 
that it can be printed and mailed to the customers physical address. 

ApproveClaim When an insurance claim is approved, a payment is issued by another 
interface on the ESB (message flow) that deals with sending the 
appropriate data to the financial partner that underwrites the particular 
policy that the customer bought. This interface is represented by an 
MQ queue and is assumed to exchange data in the Canonical 
Message Format. 


7.1.1 Prerequisites 

This scenario assumes that you have the following prerequisites: 

► WebSphere Message Broker version 8. 0.0.0 or higher installed. 

► WebSphere Message Broker Toolkit version 8.0. 0.0 or higher installed. 

► A message broker defined on the local machine with a corresponding WebSphere MQ 
queue manager. 

► Four queues are defined on the queue manager for the broker: IN, OUT, 
PAYMENT_QUEUE, and ERROR_QUEUE. 

► An SMTP email server running on the local host or access to an SMTP server for sending 
outbound email. 

► The ClaimsProcessingWcfService described in Chapter 6, “Scenario: Integration 
Windows Communication Foundation in message flows - Part 1” on page 163 is running 
on the local host. 
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► Visual Studio 2010 is installed. 

► Open XML SDK V2 installed. Download Microsoft Open XML SDK V2 at: 
http://www.mi crosoft.com/downl oad/en/detai 1 s .aspx?i d=5 124 

► Microsoft Word 2010 installed. 

If you do not have a full copy of Microsoft Word, you can download and install the Microsoft 
Word Viewer and the Microsoft Office Compatibility Pack: 

- Download Microsoft Word Viewer at: 

http://www.mi crosoft.com/downl oad/en/detai 1 s .aspx?i d=4 

- Download Microsoft Office Compatibility Pack at: 

http : //www.mi crosoft . com/downl oad/en/detai 1 s . aspx?i d=3 

7.2 Creating the message flow 

In this section, we create the message flow in the Message Broker Toolkit by dragging nodes 
from the palette onto the canvas and wiring their connections. This section defines the 
execution order of the flow and sets any node properties that are used by the flow, as 
illustrated in Figure 7-2. 

The ESQL and C# code required for each node are introduced in the subsequent sections 
that outline small groups of nodes in the flow by function. 



7.2.1 Preparing message models 

This scenario uses several predefined message models. The creation of these models is 
beyond the scope of this book, so they are provided as WebSphere Message Broker libraries 
that can be referenced from the project you use to develop your message flow. 
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The message model libraries provided have the following functions: 

ClaimsProcessingCanonicalMessageModel 

An XML schema for the XMLNSC parser that models a Canonical 
message structure that is used for data exchange between services 
on the ESB. The Canonical format makes it easier for services to be 
composed into larger enterprise applications because it provides a 
common data integration point. 

ClaimsProcessingDFDLMessageFormats 

The MQ applications that use the service send data based on a 
combination text/binary format that used sequences of Initiators, 
Delimiters, and Terminators to define where parts of the data start and 
end. This project models the data for these applications using the Data 
Format Description Language (DFDL). 

ClaimsProcessingSOAPImportedLibraries 

The SOAP interface for the flow was built by dragging and dropping a 
WSDL onto the SOAPInput node. For this to work, the WSDL for this 
service must be imported into the Message Broker Toolkit where 
changes are made to ensure that the structure of referenced schemas, 
such as the SOAP envelope, are in the correct locations. This project 
already had this import step performed. 

Importing message models 


Additional materials: The message model libraries used in this section are in the 
additional materials as WCFCIient\Project Interchange files\MessageModelPl.zip. 


In this section, the steps for importing Claims Processing Canonical Message Model, Claims 

Processing DFDL Message Formats, and Claims Processing SOAP Imported Libraries are 

covered in detail. 

Use the following procedure to import message models: 

1 . Open the Message Broker Toolkit, and enter a new workspace name. You are now in the 
Broker Application Development perspective with an empty workspace that is ready for 
new projects to be added and created. 

2. Right-click in the Application Development pane, and select Import. Select Other 
Product Interchange, and click Next. 

3. Click Browse, and locate the project interchange file, and then select the three message 
model projects, as shown in Figure 7-3 on page 278. 


Chapter 7. Scenario: Integrating Windows Communication Foundation in message flows - Part 2 


277 





Figure 7-3 Browse for a root directory 

4. Click Finish. 

7.2.2 Creating the message flow 

In this section, we create the message flows, create a new application, and import mapping 
models for our scenario. 

Creating a new application called ClaimProcessing 

Use the following procedure to quickly outline how to create a new application. These easy 
steps create efficiency, accuracy, and help standardize the process: 

1 . Select File -» New ->• Application 

2. Name the application Cl aimProcessi ng as shown in Figure 7-4. Click Finish. 


!□ New Application 


Create a new application 

An application is a deployable container that provides isolation at runtime. Enter a name for the 
new application. 

Application name | ClaimProcessingl 




Figure 7-4 The new application panel in WebSphere Message Broker 
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Adding references to the libraries 

The next step is to add references to the libraries: 

1 . Right-click the ClaimProcessing application in the Application Development pane, and 
select Properties. 

2. Select Project References and then select ClaimsProcessingDFDLMessageFormats, 
ClaimsProcessingCanonicalMessageModel, and ClaimsProcessingSOAPImported, 

as shown in Figure 7-5. Click OK. 



Figure 7-5 Assigning project references in WebSphere Message Broker 


Importing mapping modules 

After adding the references to the library, the next step is to import the mapping modules. Use 
the following procedure to import the modules CanonicaIXMLNSCToDFDL.map and 
DFDLToCanonicaIXMLNSCMap.map. 


Additional materials: The maps are in the additional materials for this book in the 
WCFCIient\Maps folder. 


1 . Right-click ClaimProcessing and then select Import. 

2. Select General File System, and click Next. 

3. Click Browse to locate and select the folder where the maps are located. Click OK. 

4. Select CanonicaIXMLNSCToDFDL.map and DFDLToCanonicaIXMLNSCMap.map, as shown in 
Figure 7-6 on page 280. Click Finish. 
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Figure 7-6 Importing the .map files 


Note: If you see errors on the imported maps, make sure that you added the references to 
the libraries. Then, rebuild the workspace using the following steps. 

1 . Go to Project -> Clean. 

2. Select Clean all projects and click OK. 


Creating a new message flow 

Use the following procedure to create a message flow for the ClaimProcessing application: 

1 . Click File New Message Flow. 

2. Enter the name ClaimProcessFlow, and click Finish. 

7.2.3 Creating and connecting the nodes 

The workspace is now ready for the message flow to be built. This section takes you through 
the process of adding and configuring the nodes in the flow. 

Creating the SOAP Input node using a WSDL file 

To create a SOAP input node: 

1 . Select the ClaimsProcessingSOAP.wsdl file from the ClaimsProcessingSOAPImported 
library, and then drag-and-drop it on to the canvas, as shown in Figure 7-7 on page 281 . 
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Figure 7-7 Dragging and dropping a file on to the canvas to create a SOAP input node 


2. Accept the default configuration on the Configure New Web Service Usage dialog, and 
click Finish, as shown in Figure 7-8. 



Figure 7-8 Configure a new web service 
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3. Right-click the subflow ClaimsProcessingSOAP node, and select Delete, as shown in 
Figure 7-9. 


50AP Input 


wmh 


fclaimsProc 


: v? Undo Move 
Redo 

Ctrl+Z 

Ctrl+Y 

Create Connection 


Open 5ubflow 

F3 

°fc Cut 
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® Copy 
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Delete 


') □ 

I :> 


50AP Reply 


Figure 7-9 Delete a subflow 


Creating the remaining nodes using the palette 

To complete our message flow application, we must add, name, and connect (wire) the 
remaining nodes. In “Creating the SOAP Input node using a WSDL file” on page 280, we 
used the ClaimsProcessingSOAP.wsdl file to create the SOAP input and SOAP Reply nodes. 
In this section, we show you how to add the rest of the nodes for our application using nodes 
provided on the palette. 

Table 7-1 provides the location, the icon, and type of the node, what you need to rename the 
nodes after you drag-and-drop them on to the canvas from the palette, and how you need to 
wire them to other nodes. 

When building a message flow, keep in mind the following items: 

► Use your cursor to drag-and-drop the nodes from the palette to the canvas. 

► To rename a node, right-click the node name, and select Rename. 

► To connect (wire) a node to another node, click the output terminal for the first node, and 
then click the input terminal on the next node in the flow. 

As you build the message flow, use Figure 7-2 on page 276 as a reference for what you want 
the completed message flow to look like. 


Table 7-1 Node naming and wiring information 


Palette drawer / 
node type 

Node name 

Wiring information 

(terminal: to input terminal on node) 

Web Services 

SOAP Input 

SOAP Input 

► Out: SOAP Extract 

Web Services 

SOAP Extract 

SOAP Extract 

► Out: SOAPToCanonicaIXML 

Transformation 

Compute 

SOAPToCanonicaIXML 

► Out: CallWCFService 

Transformation 

.NETCompute 

CallWCFService 

► Out: Flow Order 

WebSphere MQ 

MQInput 

MQ Input 

► Failure: ConvertExceptionListToMessage 

► Out: DFDLToCanonicaIXMLNSC 

► Catch: ConvertExceptionListToMessage 
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Palette drawer / 
node type 

Node name 

Wiring information 

(terminal: to input terminal on node) 

Transformation 

Mapping 

DFDLToCanonicaIXMLNSC 

► Out: Try Catch 

Construction 

TryCatch 

Try Catch 

► Try: CallWCFService 

► Catch: IncompleteResults 

Routing 

Filter 

IncompleteResults 

► True: BuildlncompleteResultsResponse 

► False: ConvertExceptionListToMessage 

► Unknown: ConvertExceptionListToMessage 

Transformation 

.NETCompute 

BuildlncompleteResultsResponse 

► Out: Flow Order 

Transformation 

Compute 

ConvertExceptionListToMessage 

► Out: SendToErrorQueue 

WebSphere MQ 

MQOutput 

SendToErrorQueue 

► Out: BuildErrorReplyMessage 

Transformation 

Compute 

BuildErrorReplyMessage 

► Out: SendReply 

WebSphere MQ 

MQOutput 

SendReply 

(none, end of flow) 

Construction 

FlowOrder 

Flow Order 

► First: Flow Orderl 

► Second: MQorSOAP 

Construction 

FlowOrder 

Flow Orderl 

► First: PaymentNeeded 

► Second: PolicyDocsNeeded 

Routing 

Filter 

PaymentNeeded 

► True: GeneratePaymentCanonicalMessage 

Transformation 

.NETCompute 

GeneratePaymentCanonicalMessage 

► Out: ToPaymentQueue 

WebSphere MQ 

MQOutput 

ToPaymentQueue 

(none, end of flow) 

Routing 

Filter 

PolicyDocsNeeded 

► True: GenerateWordAttachment 

Transformation 

.NETCompute 

GenerateWordAttachment 

► Out: Flow Order2 

Construction 

FlowOrder 

Flow Order2 

► First: EmailToCustomer 

► Second: MoveAttachmentToBody 

Email 

EmailOutput 

EmailToCustomer 

(none, end of flow) 

Transformation 

Compute 

MoveAttachmentToBody 

► Out: SendForPrinting (In) 

File 

FileOutput 

SendForPrinting 

(none, end of flow) 

Routing 

Filter 

MQorSOAP 

► True: CanonicaIXMLNSCToDFDL 

► False: CanonicaIXMLToSOAP 
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Palette drawer / 
node type 

Node name 

Wiring information 

(terminal: to input terminal on node) 

Transformation 

Compute 

CanonicaIXMLToSOAP 

► Out: SOAP Reply 

Web Services 

SOAPReply 

SOAP Reply 

(none, end of flow) 

Transformation 

Mapping 

CanonicaIXMLNSCToDFDL 

► Out: SendReply 

WebSphere MQ 

MQOutput 

SendReply 

(none, end of flow) 


7.2.4 Configuring node properties 

In this section, we tell you how to configure the properties for the following nodes in the 
message flow: 

► MQ Input 

► DFDLToCanonicaIXMLNSC 

► EmailToCustomer 

► SendForPrinting 

► CanonicaIXMLNSCToDFDL 

To define node properties, display the Properties view by right-clicking a node and selecting 

Properties. 

MQ Input node 

To define properties for the MQ Input node: 

1 . In the Input Message Parsing tab, use the drop-down list on the Message domain field to 
select DFDL: For binary or text messages with a Data Format Description Language 
schema model, as shown in Figure 7-10. 


Properties £if ' 

rS v ° n 

]@!i MQ Input Node Properties - MQ Input 



Description 


Basic 


Input Message Parsing 


Parser Options 


Advanced 


Validation 


Security 


Instances 


Monitoring 


Message domain 
Message model 
Message 

Physical format 


with a Data Format Description Languag 


cription Language scherr 


XMLN5C : For XML messages (namespace aware, validation low memory use) 

DataObject : For data from WebSphere Adapters, CORBA and Database records 

JSON : For JavaScript Object Notation messages 

BLOB : For messages with an unspecified format 

MIME : For MIME wrapped data including multipart 

MRM : For binary or text messages that are modeled in a message set 

JMSMap : For JMS MapMessage messages (XML) 

JMSStream : For JMS StreamMessage messages (XML) 

XMLN5 : For XML messages (namespace aware) 


“3 


Figure 7-10 Select a message domain 


2. Click the Browse button next to the Message field, and then select the DFDL schema for 
REQUESTMESSAGE, as shown in Figure 7-1 1 on page 285. Click OK. 


284 Using WebSphere Message Broker V8 in Mid-Market Environments 





Figure 7-11 Configuring the MQ Input node 
3. Press Ctrl+S to save your changes. 

DFDLToCanonicaIXMLNSC node 

Use the following procedure to define properties for the DFDLToCanonicaIXMLNSC node: 

1 . In the Basic tab, click the Browse button next to the Mapping routine field for the mapping 
routine property, as shown in Figure 7-12. 



Figure 7- 12 Browse for a mapping routine 

2. Select {default}:DFDLToCanonicalXMLNSCMap, as shown in Figure 7-13 on page 286 
and click OK. 
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D Data Transformation Map Selection 
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Filter names (? = any character, * = any String): 


Select a Data Transformation Map 
S -(default)- : CanonicalXMLNSCT oDFDL 


-(default)- : DFDLToCanonicalXMLNSCMap 


Location: 


k=7 ClaimProcessing 


OK 


Cancel 


Figure 7-13 Select a mapping routine 


3. Press Ctrl+S to save your changes. 

EmailToCustomer node 

Use the following procedure to define properties for the EmailtoCustomer node: 

1 . In the Basic tab, enter a location for the SMTP server name and port number. This 

property defines the SMTP server and port to which emails are sent to from this node. The 
value for this is in the format server: port (for example: my. smtp. server: 25). In our 
scenario, we use my. smtp. local host as a basic example, as shown in Figure 7-14. The 
port value is optional, but if you do not specify a port value, the default value is 25. 



Figure 7-14 Specify an SMTP server and port 
2. Press Ctrl+S to save your changes. 
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Note: You can also specify an alias value for this property. If the alias exists at runtime, 
the specified values are used. If the alias does not exist at runtime, the broker assumes 
the value to be a valid SMTP host. 

You can configure the alias for SMTP server and port number as a broker external 
resource using WebSphere Message Broker Explorer or 
mqsicreateconfigurableservice command. More information is available at: 

http : //publ ib.boul der.i bm.com/i nfocenter/wmbhel p/v8r0m0/topi c/com. ibm.etool s 
.mft .doc/ac66360_. htm 


3. Define a user defined property for the node using the following steps: 

a. Click the User Defined Properties tab on the bottom of the message flow editor. 

b. Right-click ClaimProcessFlow ->• Basic, and select Add Property. 

c. Rename the property FromEmai 1 . 

d. In the Default value field, enter the URL of the location you want to specify as the 
sending location for emails. In our example, we use 
ITSOExampleEmail@itso.example.ibm.com, as shown in Figure 7-15. 



Figure 7-15 Define user defined properties 

4. Press Ctrl+S to save your changes. 

5. Switch back to the Graph view. 

User-defined properties are defined at the flow level and do not need to be promoted. When 
you create a BAR file for deployment, you have the opportunity to configure the property. 

SendForPrinting node 

Use the following procedure to define properties for the SendForPrinting node. For this node, 
we want to configure the file action property so that it replaces the file, if there is a file that 
already exists, and promotes the Directory property so that it can be configured in the BAR 
file: 

1 . Right-click the SendForPrinting node, and select Promote Property. 
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2. From the available node properties, select Basic Directory, as shown in Figure 7-1 6. 
Click Promote. 


B 


Promote Property 


Available node properties: 


Promoted properties: 


±L 


5endForPrinting 
l[_u[| Basic 

□ Action if file exists 

r. — 

H File name or pattern 

□ Mode for writing to file 
H Replace duplicate archi 

S FTP 

□ Action if remote file exi 

□ Remote Transfer 

□ Retain local file after tr 

■ Security identity 
j 1 Server and port 

I 




Figure 7-16 Promote a property 

3. In the Target Selection window, select the default group, ClaimProcessFlow, and click 
OK. 

4. The Directory property will now display in the promoted properties list, as shown in 
Figure 7-17. Click OK. 



Figure 7-17 Promoting properties in file output nodes 

5. In the Basic tab, in the Properties view for the node, verify that the Directory property was 
promoted, as shown in Figure 7-18 on page 289. 
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Figure 7-18 Verify the directory property was promoted 


Directory 

File name or pattern 


3 


File action 

Mode for writing to file 

C Write directly to the output file (append if file exists) 

(* 5tage in mqsitransit directory and move to output directory on "Finish file" 

Action if file exists (Replace Existing File 
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6. Select the Request tab, specify $Body for the data location (this is the default), and specify 
$Local Envi ronment/Desti nati on/Emai 1 /Attachment/ContentName for the request file 
name property location, as shown in Figure 7-19. 
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Figure 7-19 Defining location information for the file output node 


7. Press Ctrl+S to save your changes. 

CanonicaIXMLNSCToDFDL node 

Use the following procedure to define properties for the CanonicaIXMLNSCToDFDL node: 

1 . In the Basic tab, click the Browse button for the Mapping routine property, as shown in 
Figure 7-20. 



Figure 7-20 Browse for a mapping routine 

2. Select {default}:CanonicalXMLNSCToDFDL, as shown in Figure 7-21 on page 290. 
Click OK. 
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Figure 7-21 Select a transformation map 
3. The selected value is added. Press Ctrl+S to save your changes. 

7.2.5 Queue names 

Some of the nodes in the message flow need to have Queue names configured. Use 
Table 7-2 to configure the properties for the nodes listed in the table. Accept the default 
values for all properties unless an alternative value is listed in the table. 

Table 7-2 Queue naming for nodes in the flow 


Node 

Tab 

Property 

Value 

MQ Input 

Basic 

Queue name 

IN 

ToPaymentQueue 

Basic 

Queue name 

PAYMENT_QUEUE 

SendToErrorQueue 

Basic 

Queue name 

ERROFLQUEUE 

SendReply (both nodes) 

Advanced 

Destination 

mode 

Destination List 


7.3 Using the Mapping node to transform the input to the 
Canonical Message Format 

The input from the MQ transport is in a record-oriented text/binary format modeled in Data 
Format Description Language (DFDL). DFDL is an Open Grid standard for modelling text and 
binary formatted messages using XML. WebSphere Message Broker includes support for the 
DFDL domain with a new DFDL parser in the broker runtime and a new set of message 
modelling tools in the Message Broker Toolkit. The DFDL parser supersedes the MRM 
parsers and is the only supported way to create new message models in version 8 of 
WebSphere Message Broker. The placement of the DFDL node is highlighted in the message 
flow shown in Figure 7-22 on page 291 . 
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Figure 7-22 DFDL node 


Note: The MRM parsers still exist in the broker runtime, so any existing projects or bar files 
from previous versions of WebSphere Message Broker will still continue to work. 


The message model information is held in the ClaimsProcessing.xsd file in the 
ClaimsProcessingDFDLMessageFormats library, as shown Figure 7-24 on page 292. 
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Figure 7-23 ClaimsProcessing.xsd location 


Double-click ClaimsProcessing.xsd to open it. 

In the REQUEST message, one of a number of types based on the operation can be called. 
Each operation has different children based on the information that needs to be supplied. In 
Figure 7-23, you can see a CREATECLAIMREQUEST that was expanded to show the detail. 
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Name 

Type 

Min Occurs 

Max Occurs Default Value 

j Sample Value 

0 |¥| REQUESTMESSAGE 

0 -£* choice 


1 

1 


0 CREATECLAIMREQUEST 


1 

1 


□ □□□ sequence 


1 

1 


0 [I] CLAIM 

CLAIM 

1 

1 


0 sequence 


1 

1 


\¥\ DATE 

dateTime 

1 

1 

20 12-Q4-22T14: 00 : 00 

\e\ DATERECVD 

dateTime 

0 

1 

200 1-1 1-22T12: 00 : 00 

mm 

string 

1 

1 <empty string > 

CLAIM001 

[e] CUSTREF 

string 

1 

1 

CUST0Q1 

[e] POLICYREF 

string 

1 

1 

POLICY001 

[¥] STATUS 

<string> 

1 

1 

Submitted 

[e] VALUE 

int 

1 

1 

2147483647 

[e] DESCRIPTION 

string 

1 

1 

This is a claim for an accident that occured while driving my car 

[e] NOTES 

string 

1 

1 

The claims agent can add some notes into the claim data 

0 [e] CUSTOMERLIST 

CUSTOMER 

1 

1 


0 □□□ sequence 


1 

1 


\e\m 

string 

1 

1 

CUST001 

0 © NAME 

NAME 

1 

1 


© ADDRESS 

string 

1 

1 

1 Generic Street, Any town, USA 

© EMAIL 

string 

1 

1 

johndoe @itso . example . ibm . com 

© ^ CREATEPOLICYREQUEST 


1 

1 


0 ^ MODIFYCLAIMREQUEST 


1 

1 


© ^ VIEWCLAIMREQUEST 


1 

1 


© VIEWOUTST ANDINGCLAIMSREQUEST 


1 

1 


© ^ VIEWPOLICYREQUEST 


1 

1 


Add a Local Element 


Figure 7-24 The REQUESTMESSAGE displayed in the DFDL Editor 


Covering the building of the DFDL message model is beyond the scope of this chapter. 
However, you can examine the properties of individual elements to see how they are 
represented on the wire. For example, Figure 7-25 shows that the CLAIM element has an 
initiator of CLAIMLIST. 
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j Name 
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1 

1 
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1 

1 


0 »nn sequence 


1 

1 
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1 


0 -no sequence 


1 

1 


© DATE 

dateTime 

1 

1 


[e] DATERECVD 

dateTime 

0 

1 


gio 

string 

1 

1 

<empty string; 

© CUSTCEF 

string 

1 

1 


© POLICYREF 

string 

1 

1 


© STATUS 

<string> 

1 

1 


[ej VALUE 

int 

1 

1 

1 

© DESCRIPTION 

string 

1 

1 


© NOTES 

string 

1 

1 


0 © CUSTOMERLIST 

CUSTOMER 
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1 



INI 
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^ Representation Prope [E] Asserts and Discrimi >J l 
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CD 
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CD 

CD 

CD 


Figure 7-25 The Representation Properties of the CLAIM element displayed in the DFDL editor 


This initiator is highlighted in Figure 7-26 on page 293, which shows a hexadecimal view of a 
sample CREATECLAIM message. 
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0000 

43 

52 

45 

41 

54 

45 

43 

4 c 

41 

49 

4d 

1 43 

4 c 

41 

49 

4d 1 

C RE ATE C LAIM|CLAIM| 

0010 

|4c 

49 

53 

54 

43 

4 c | 

41 

49 

4d 

32 

30 

31 

32 

2d 

30 

34 

|LI5TpLAIM2 012 .04 

0020 

2d 

32 

32 

20 

30 

32 

3a 

30 

30 

3a 

30 

30 

2c 

32 

30 

30 

.22.02.00.00.200 

0030 

31 

2d 

31 

31 

2d 

32 

32 

20 

31 

32 

3a 

30 

30 

3a 

30 

30 

1.11.22.12.00.00 

0040 

2c 

43 

4c 

41 

49 

4d 

30 

30 

30 

32 

2c 

43 

55 

53 

54 

30 

. CLAIM00Q2 . CUSTO 

0050 

30 

31 

2c 

50 
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4c 

49 

43 

59 

30 

30 

31 

2c 

53 

75 

62 

01 . POLICYOOl . Sub| 

0060 

6d 

69 
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Figure 7-26 The CreateClaim Initiator 


To transform the input message from the DFDL domain into an XMLNSC CanonicalMessage, 
the Graphical Data Mapper is used. A map called DFDLToCanonicaIXMLNSCMap is already 
defined for the DFDLToCanonicaIXMLNSC node. You can double-click the node to explore the 
map. 

As shown in Figure 7-27 on page 294, the main map has a set of local maps that are 
executed conditionally depending on the type of input message received. The condition can 
be any XPath expression. In this example, we use the count () function to test if the 
CREATECLAIMREQUEST element exists in the tree. 
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Figure 7-27 The top level map for the DFDLToCanonicaIXMLNSC node 


The Graphical Data Mapper allows a transformation to be built by dragging connections 
between data elements. This is ideal for rapid development scenarios since no code needs to 
be written to achieve the mapping. Figure 7-28 shows the local map that maps the 
CreatePolicy operation. This map uses a mixture of Move, Assign, and For-each constructs to 
convert the DFDL message into XMLNSC. 



Figure 7-28 Mapping the CreateClaim operation 


An example of the transformation performed by the CREATECLAIM message shown in 
Figure 7-26 on page 293 is mapped to XMLNSC. 
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Example 7-1 shows the output. 

Example 7-1 A CreateClaim request in XMLNSC Canonical Message Format 

<?xml version= M 1.0 M encoding= l, UTF-8 l, ?> 

<cp: Canon i cal Message 

xml ns : cp="http: //www. i bm.com/WebSphereMessageBroker/Exampl es/Cl aims Process i ng/Cano 
ni cal Message" xml ns : xs i = 11 http: //www. w3.org/2001/XMLSchema-i nstance" 
xsi : schemaLocation=" http: //www. i bm.com/WebSphereMessageBroker/Exampl es/Cl aimsProce 
ssing/Canoni cal Message . ./Resource/di fferentmsgs/CannonicalMessageModel .xsd "> 
<cp:Header> 

<AppId>AppId</AppId> 

<MsgId>MsgId</MsgId> 

<Requester>Requester</Requester> 

<Transmi ssi onDate>2001-12-31T12 :00:00</Transmi ssionDate> 
<Command>Command</Command> 

<Busi nessUnit>Businessllni t</BusinessUni t> 

<Busi nessUni tCode>Busi nessUni tCode</Busi nessllni tCode> 

</cp:Header> 

<Appl i cati onMessage> 

<C1 aimsProcessi ngRequest> 

<NewCl aimRequest> 

<NewCl aim> 

<C1 aimDate>2012-04-22T02:00:00</Cl aimDate> 

<C1 aimRecei vedDate>2001-ll-22T12:00:00</Cl aimRecei vedDate> 

<C1 aimReference>CLAIM0002<Cl aimReference> 

<C1 aimVal ue>2147483647</Cl aimVal ue> 

<Customer> 

<CustomerId>CUST001</CustomerId> 

<Fi rstName>John</Fi rstName> 

<OtherNames> 

<Name>James</Name> 

</OtherNames> 

<Surname>Doe</Surname> 

<Address>l Generic Street, Any town, USA</Address> 

<Emai 1 >j ohndoe@i tso . exampl e . i bm. com</Emai 1 > 

</Customer> 

<Description/> 

<Notes> 

The claims agent can add some notes into the claim data 
<Note> 

<Pol i cyNumber>P0LICY001</Pol i cyNumber> 

<Status>Submi tted</Status> 

</NewCl aim> 

<RequestedDate>2012-03-15T20:38:22</RequestedDate> 

</NewCl aimRequest> 

</Cl aimsProcessi ngRequest> 

</Appl i cati onMessage> 

<cp:Trailer> 

<Created>2012-03-28T12:00:00</Created> 

<LastModi fi ed>2012-03-28T12:00:00</LastModi fi ed> 

<LastModi fi edBy>LastModi f i edBy</LastModi fi edBy> 

</cp:Trai 1 er> 

</cp: Canon i cal Message> 
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7.4 Transforming the SOAP input message 


Messages that arrive at the SOAP Input node have their message extracted and converted to 
canonical XML format. This section shows the process that performs this function. The 
process is highlighted in Figure 7-29. 



The SOAP Input message for this flow contains only the ClaimReference information of the 
claim that needs to be returned. An example input message is shown in Example 7-2. 

Example 7-2 SOAPInput Message example 

<soapenv: Envelope xml ns :soapenv=" http: //schemas. xml soap.org/soap/envelope/" 

xml ns : soap="http: //www. i bm.com/WebSphereMessageBroker/Exampl es/Cl aimsProcessi ng/SO 

APMessage"> 

<soapenv:Header/> 

<soapenv: Body> 

<soap:ClaimRefEl ement>CLAIM0001</soap:Cl aimRefEl ement> 

</soapenv:Body> 

</soapenv : Envel ope> 


To transform this message to the Canonical Message Format, the SOAP Envelope first needs 
to be removed. WebSphere Message Broker provides the SOAPExtract node to perform this 
task. The default properties for this node are correct for the scenario. 


Note: The SOAPExtract node places the removed SOAP Envelope in the 
LocalEnvionrment tree where it can be used by other parts of the flow. In this example, we 
allow the SOAP Reply node to generate a new output SOAP Envelope; however, one 
common pattern is to retrieve this SOAP Envelope from the Local Environment prior to 
making the reply. 


After the SOAP Envelope is extracted, it is easy to construct some ESQL to move the 
ClaimRef element into an appropriate place in the CanonicalMessage model. However, there 
is a lot of information that is required by the Canonical Message Format that is not supplied by 
the input message. The SOAPToCanonicaIXML ESQL compute node is used to assign 
default values to these fields. 
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To transform this message to the Canonical Message Format, by removing the SOAP 
Envelope: 

1 . Double-click the SOAPToCanonicaIXML Compute node to open the ESQL for the node. 

2. Add the following namespace declaration at the top of the ESQL file: 

DECLARE sp NAMESPACE 

1 http://www. i bm.com/WebSphereMessageBroker/Exampl es/Cl aimsProcessi ng/SOAPMessage 1 ; 

3. Replace the generated code with the code shown in Example 7-3. 

Example 7-3 The SOAPToCanonicaIXML Compute node 

CREATE COMPUTE MODULE ConvertToCanoni cal XML 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

SET OutputRoot. Properties = InputRoot. Properties; 

--Create an XMLNSC message 

CREATE LASTCHILD OF OutputRoot DOMAIN ( 'XMLNSC' ) ; 

SET OutputRoot. XMLNSC. ns:CanonicalMessage.ns:Header.AppId = 

'WebCustomer ' ; 

SET Output Root. XMLNSC. ns: Canon i cal Message. ns: Header. Bus inessUnit = 
'OnlineOperations' ; 

SET Output Root. XMLNSC. ns: Canon i cal Message. ns: Header. Bus i nessUni tCode = 

' 0NLINE1 ' ; 

SET Output Root. XMLNSC. ns: Canon i cal Message. ns: Header. Transmi ssionDate = 
CURRENT_TIMESTAMP; 

SET OutputRoot. XMLNSC. ns:CanonicalMessage.ns:Header.MsgId = 'SOAP' || 

CAST (CURRENT_TIMESTAMP AS CHARACTER); 

SET Output Root. XMLNSC. ns: Canon i cal Mes sage. Appl i cati onMessage 
.Cl aimsProcessi ngReques t. Vi ewClaimRequest.RequestedDate = 
CURRENT_TIMESTAMP; 

SET Output Root. XMLNSC. ns: Canonical Message. Appl i cati onMessage 
.Cl aimsProcessi ngReques t . Vi ewCl aimRequest .Cl aimReference = 

FI ELDVALUE (InputRoot. XMLNSC. sp: Cl aimRefEl ement) ; 

--Create the trailer 

SET OutputRoot. XMLNSC. ns:CanonicalMessage.ns:Trailer. Created = 
CURRENT_TIMESTAMP; 

SET Output Root. XMLNSC. ns : Canonical Mes sage. ns : Trai ler. Las tModi tied = 
CURRENT_TIMESTAMP; 

SET Output Root. XMLNSC. ns : Canonical Message. ns: Trai ler.LastModi fiedBy = 
'WebSphere Message Broker ' || BrokerVersion || ' - ' |j 
BrokerName|| '.' || MessageFlowLabel ; 

RETURN TRUE; 

END; 


Example 7-4 shows the XMLNSC message after transformation by this node. 

Example 7-4 A ViewClaimRequest in XMLNSC Canonical Message Format 

<?xml version="1.0" encoding="UTF-8"?> 

<cp: Canon i cal Message 

xml ns:cp="http://www. i bm.com/WebSphereMessageBroker/Exampl es/Cl aimsProcessi ng/Cano 
ni cal Message" xml ns : xsi = " http://www.w3.org/2001/XMLSchema-i nstance" 
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xsi :schemaLocation= 11 http://www.ibm.com/WebSphereMessageBroker/Examples/ClaimsProce 
ssi ng/Canoni cal Message . ./Resource/di fferentmsgs/Cannoni calMessageModel .xsd "> 
<cp:Header> 

<AppId>WebCustomer</AppId> 

<MsgId>S0AP2012-03-28T12:23:46</MsgId> 

<Transmi ssi onDate>2012-03-28T12:23:46</Transmi ssionDate> 
<Command>Command</Command> 

<Busi nessUni t>Onl i neOperati ons</Busi nessllni t> 

<Busi nessUni tCode>ONLINEl</Busi nessUni tCode> 

</cp:Header> 

<Appl i cati onMessage> 

<C1 aimsProcessi ngRequest> 

<ViewClaimRequest> 

<C1 aimReference>CLAIMf5f81dal77294fe595512104c400ce93</Cl aimReference> 
<RequestedDate>2012-03-15T20:38:22</RequestedDate> 

</Vi ewCl ai mRequest> 

</Cl aimsProcessi ngRequest> 

</Appl i cati onMessage> 

<cp:Trailer> 

<Created>2012-03-28T12 : 23 : 46</Created> 

<LastModi f i ed>2012-03-28T12 : 23 : 46</LastModi f i ed> 

<LastModifiedBy>WebSphere Message Broker 8. 0.0.0 - 
BRK8. Cl aimsProcessi ng FI ow</LastModi f i edBy> 

</cp:Trai 1 er> 

</cp: Canon i calMessage> 


4. Close the ESQL, and in the Basic tab of the Properties view for the 

SOAPToCanonicaIXML node, enter ConvertToCanonicalXML in the ESQL module field, as 
shown in Figure 7-30. 
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Figure 7-30 Enter the name of the ESQL module 


7.5 Creating a .NETCompute node to consume the 
ClaimsProcessingWcfService 

The main function of the ClaimProcessing application is to call the service developed in 
Chapter 6, “Scenario: Integration Windows Communication Foundation in message flows - 
Part 1” on page 163. The CallWCFService .NETCompute node uses a WCF client generated 
using MEX to invoke the service. Figure 7-31 on page 299 shows the location of the 
.NETCompute node in the message flow. 
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Figure 7-31 CaiiWCFService and associated input and output connections 


To create a Visual Studio solution to contain all of the .NET code required by this scenario: 

1 . Double-click the CaiiWCFService node to open Visual Studio. 

2. Select File -» New — > Project. 

3. From the Installed Templates panel, select Visual C# -» Message Broker -» Project to 
modify a Message Broker Message. 

Perform the following steps: 

a. In the Name field, enter Cl aimsProcessi ngBrokerProject. 

b. In the Location field, use the Browse button to choose a location for your project. 

c. In the Solution name field, enter Cl aimsProcessi ngBrokerSolution. 

4. Click OK to save the project. 

The New Project Wizard creates a skeleton compute node called ModifyNode in the project 
for you in a namespace that is named after the project. It is best practice to follow Microsoft 
naming guidelines when selecting a namespace for a project. Microsoft recommends using 
the format CompanyName.TechnologyName.Qual i fi er where Qual i fier can be any unique 
dotted path. In this example, use the Ibm. Broker. Example. Cl aimsProcessi ngBroker 
namespace. Note that this is different from the namespace used in Chapter 6, “Scenario: 
Integration Windows Communication Foundation in message flows - Part 1” on page 163 for 
the WCF Service. This naming differentiation is to avoid any potential name clashes with the 
Service. 

To change the default namespace so that new files are created in the 
Ibm. Broker. Exampl e.Cl aimsProcessi ngBroker namespace: 

1 . In the Solution Explorer, right-click ClaimsProcessingBrokerProject, and select 

Properties. 

2. In the Application tab, enter Ibm. Broker. Example. Cl aimsProcessi ngBroker in the default 
namespace field, as shown in Figure 7-32 on page 300. 
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Figure 7-32 Setting the default namespace for the new project 


3. Click File Save Selected Items to save the project. 

Setting the default namespace for the project ensures that new files created in this project are 
created in the correct namespace. However, existing files are not moved into the new 
namespace. Use the following procedure to move the ModifyNode skeleton class into the new 
namespace: 

1 . Double-click ModifyNode.es in the Solution Explorer to open in the editor. 

2. Change the namespace declaration to match Example 7-5. 

Example 7-5 Updating the namespace for ModifyNode.es 
namespace Ibm. Broker . Exampl e. Cl aimsProcessi ngBroker 

3. Press Ctrl+S to save Modi fyNode . cs. 

The New Project Wizard created the ModifyNode.es skeleton file. However, rename the node 
class to something more descriptive. To rename the Modify.cs node: 

1 . In the Solution Explorer, right-click ModifyNode.es, and select Rename. 

2. Enter Cal lWCFNode.es as the new name, and press Enter. When asked if you want to 
perform a rename of all references, click Yes. 

3. If CallWCFNode is not already open for editing, double-click it in the Solution Explorer to 
open it. 

4. Make sure the class declaration has the new name: 
public class CallWCFNode : NBComputeNode 

If the name is not CallWCFNode: 

a. Highlight the class declaration for ModifyNode, right-click and select Refactor 
Rename, as shown in Figure 7-33 on page 301 . 
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Figure 7-33 Renaming the ModifyNode class 


b. In the Rename dialog, enter Cal 1 WCFNode in the New name field. Click OK. 

c. In the Preview Changes dialog, click Apply. 

5. Add references that are needed for the code in this class: 

a. Right-click References in the Solution Explorer. 

b. Select Add Reference. 

c. In the .NET tab, select System.Runtime.Serialization, and click OK. 

d. Repeat this process to add a reference to System. ServiceModel. 

6. Add the following using statements to the top of CallWCFNode.es: 

usi ng I bm. Broker. Exampl e.Cl aims Process i ng; 
using System. Runtime. Serial ization; 
using System. Servi ceModel ; 

7. Press Ctrl+S to save the class. 


7.5.1 Creating a constant to hold the namespace prefix 

Throughout this example, the Canonical Message model’s namespace is referred to often 
when navigating the logical message tree. To avoid having to use this string inline in the code 
or having to define it multiple times, you can create a constant that can be referred to by any 
of the files in this project. 

Because the constant is used for multiple diverse nodes, you can create a new Constants 
class to hold the namespace prefix constant. 

To add the Constants class: 

1 . Select Project ->• Add Class. 

2. In the Installed Templates menu, select Visual C# Items. 

3. Select Class. 

4. In the Name field, enter Constants . cs. Click Add to add the class. 

5. Modify the code for Constants.es so that it matches Example 7-6. 

Example 7-6 Constants.es 

namespace Ibm. Broker. Exampl e.Cl aimsProcessi ngBroker 

{ 

public class Constants 

{ 
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public const string cp = 

11 http: //www. i bm.com/WebSphereMessageBroker/Exampl es/Cl aims Process i ng/Canoni calM 
essage" ; 

} 

} 


6. Press Ctrl+S to save the class. 

7.5.2 Adding the MEX-generated WCF client to the project 

In 6.5, “Generating WCF client code from a MEX enabled WCF service” on page 248, you 
generated a WCF client using the svcuti 1 tool. To allow the .NETCompute node code to 
invoke the service, this generated client needs to be imported into the project. 

To import the client: 

1 . Select Project Add Existing Item. 

2. In the Add Existing Item dialog, change the Objects of Type drop-down list to read A1 1 
Files (*.*). 

3. Navigate to the location holding the svcutil output. 

4. Find the two files called Cl aimsProcessi ngWcfServi ce.cs and output .config. Select both 
of these files. Click Add. 

5. Right-click the output.config file from the Solution Explorer, and select Rename. 

6. Name the file App . Conf i g, and press Enter. 

7. Save the project. 

You will now have two new files in the Solution Explorer: App.config and 
ClaimsProcessingWcfService.es. 

The App.config file contains a WCF ABC specification of the ClaimsProecssingWcfService. 
The generated code is shown in Example 7-7. 

Example 7-7 An ABC specification allowing the client to invoke the ClaimsProcessingWcfService 

<?xml version="1.0" encodi ng= M utf-8"?> 

<configuration> 

<system. servi ceModel > 

<bindings> 

<netTcpBinding> 

<binding name= l, TcpIpEndPoint 11 cl oseTimeout="00:01 :00" openTimeout="00:01 :00" 
recei veTimeout="00: 10:00" sendTimeout= M 00:01 :00" transact!* on FI ow="fal se" 
transferMode= l, Buffered M transact!* onProtocol ="01 eTransacti ons" 
hostNameCompari sonMode =l, StrongWi 1 dcard" 1 i stenBackl og=" 10" 
maxBufferPool Si ze="524288 M maxBufferSi ze= l, 65536" maxConnecti ons=" 10" 
maxRecei vedMessageSi ze="65536"> 

<readerQuotas maxDepth= l, 32" maxStri ngContentLength= l, 8192 M maxArrayLength=" 16384" 
maxBytesPerRead= M 4096 M maxNameTabl eCharCount= M 16384" /> 

<rel i abl eSession ordered= l, true" i nacti vityTimeout= "00: 10:00" 
enabled="fal se" /> 

<security mode="Transport"> 

<transport cl !*entCredent!*alType="Windows" protect!* onLevel ="EncryptAndSign" /> 
<message cl !*entCredent!‘alType="Windows" /> 

</security> 

</bi ndi ng> 
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</netTcpBinding> 

</bindings> 

<cl ient> 

<endpoi nt address = "net. tcp://l ocal host : 8523/ 11 bi ndi ng="netTcpBi ndi ng" 
bi ndi ngConf i gurati on= M TcpIpEndPoi nt" contract=" I Cl aims Process i ngWcfServi ce" 
name =l, TcpIpEndPoi nt"> 

<identity> 

<userPrinci pal Name value= l, DAVICRIGW500\davicn'g 11 /> 

</identity> 

</endpoint> 

</cl ient> 

</system. servi ceModel> 

</confi gurati on> 


Note: The svcutil utility generated default configuration options for the client based on the 
transport being used. In this instance, the maxReceivedMessageSize is set to 65536. The 
svcutil gave these configuration options inline rather than using a binding configuration. 
The configuration options are specific to the client and not necessarily the same as the 
service. For example, it is possible to permit the client to read larger messages than the 
service and vice versa. The configuration options do not form part of the Service Contract 
between the client and the service. 


Notice that the code in the ClaimsProcessingWcfService file that you added looks 
substantially different from the code for the class you created in 6.3, “Developing the WCF 
Service” on page 168. This difference is because the file actually contains a proxy for the 
WCF service. If you examine the proxy class in the Class View, you will see that this proxy 
object consists only of the methods defined in the Service Contract, as shown in Figure 7-34. 
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Figure 7-34 Examining the WCF proxy in the class view 


After the WCF client is added to the project, any other class in the project can instantiate the 
proxy using code, as shown in Example 7-8 on page 304. 
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Example 7-8 Instantiating a new WCF client for the ClaimsProcessingWcf Service 


ClaimsProcessingWcfServiceClient serviced ient = new 
Cl aims Process i ngWcfServi ceCl i ent () ; 


7.5.3 Developing helper methods to interact with the WCF service 

To separate concerns within the code, a single method in the .NETCompute node will handle 
all of the calls to the WCF client. This allows error handling associated with the client to be 
handled in one location. 

For this example, a single instance of the client object is shared by all threads accessing the 
flow. The actual client constructor is called inline using a lazy loading pattern in the main line 
of code execution. To do so, the proxy object must be declared as a static data member of the 
node class. 

Add the following code to the class definition for the CallWCFNode: 

private static Cl aimsProcessi ngWcfServi ceCl ient serviced ient = null; 

Not constructing the proxy when we construct the node means that construction of the proxy 
and reconstruction in an error scenario are handled by the same code block, which simplifies 
the application code needed. This also means that we need to take a lock on the object in 
fewer locations in the code. 


Note: Constructing the static object in either the node constructor or during static 
initialization for this example is safe without taking a lock because Broker node framework 
will not allow a thread to drive the evaluate method until after the node constructor has 
completed and static initialization can only occur once for each class per Application 
Domain. 


7.5.4 Concurrency 

Although access to the proxy objects Service Contract methods are threadsafe, there are 
several complications to consider when using a WCF proxy in a multi-threaded environment, 
such as in a message flow with multiple additional instances. 

Although the underlying communication is threadsafe and callers to the service do not receive 
messages intended for another thread, this is not the same as supporting concurrent access. 
If the underlying communication channel is not fully concurrent, requests might be queued by 
the channel. 

Additionally, if one of the requests faults the channel, the application code has to cope with 
reinitializing the proxy and deal with the synchronization issues that result from this 
considerations. 

To simplify the access to the WCF proxy object, the access is serialized so that only one 
message flow thread can make a WCF invocation at a time. In a production system where 
performance is critical, you might consider using a pooled approach to proxy objects or 
creating a proxy for each message flow thread, storing the proxy in thread local storage. 
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In this example, serialization is performed using the C# lock call to obtain a mutual exclusion 
lock on a static member of the node class: 

1 . Add the code shown in Example 7-9 to the class definition for CallWCFNode to create the 
static object to use for locking. 

Example 7-9 Creating a static Object to use for serializing access to the WCF proxy 
private static Object proxyLock = new Object (); 


The WCF service invocation is performed by a method called 

CallClaimsProcessingService that takes a ClaimsProcessingRequest as input and returns 
a ClaimsProcessingResponse. The message signature uses the base classes so that no 
matter what type of request is being performed all execution will pass through this method. 
This is important so that the lock operates on all service invocations. 

2. Add the code shown in Example 7-10 to the class definition of CallWCFNode. 

Example 7-10 The CallClaimsProcessingService method in CallWCFNode.es 

private Cl aimsProcessi ngResponse Cal 1 Cl aimsProcessi ngServi ce(Cl aimsProcessi ngRequest 
request) 

{ 

//we must be the only thread accessing the shared client 
lock (proxyLock) 

{ 

if (serviced ient == null |j 

servi ceCl i ent . InnerChannel .State . Equal s (Communi cati onState. Faul ted) ) ) 

{ 

serviced ient = new Cl aimsProcessi ngWcfServiceCl ient () ; 

} 

try 

{ 

Cl aimsProcessi ngResponse response; 
swi tch (request . TypeOf Request) 

{ 

case RequestType. Approved aim: 

response=servi ceCl i ent .Approved aim( (Approved ai mRequest) request) ; 
break; 

case RequestType. CreatePol icy: 

response=servi ceCl i ent .CreatePol i cy ((CreatePol i cyRequest) request) ; 
break; 

case RequestType. NewCl aim: 

response=servi ceCl i ent . Created aim( (NewCl ai mRequest) request) ; 
break; 

case RequestType. RejectCl aim: 

response=servi ceCl i ent .RejectCl aim( (RejectCl ai mRequest) request) ; 
break; 

case RequestType. Vi ewCl aim: 

response=servi ceCl i ent .Vi ewCl aim( (Vi ewCl ai mRequest) request) ; 
break; 

case RequestType. Vi ewOutstandi ngCl aims: 

response=servi ceCl i ent .Vi ewOutstandi ngCl aims ( 

(Vi ewOutstandi ngCl aimsRequest) request) ; 

break; 

case RequestType. Vi ewPol icy: 

response=serviceCl ient. Vi ewPol icy( (Vi ewPol i cyRequest) request) ; 
break; 
defaul t : 

throw new NBRecoverableException( 

"Unrecogni sed Cl aimsProcessi ng Command 11 + request .TypeOfRequest) ; 
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} 

return response; 

} 

catch (Exception e) 

{ 

/* WCF can cause the following exceptions: 

* System. TimeoutExcepti on 

* System. Servi ceModel .CommunicationException 

* System. Servi ceModel .AddressAl readylnllseException 

* System. Servi ceModel .AddressAccessDeniedException 

* System. Servi ceModel .CommunicationObjectFaul tedException 

* System. Servi ceModel .CommunicationObjectAbortedException 

* System. Servi ceModel . EndpointNotFoundException 

* System. Servi ceModel .Protocol Exception 

* System. Servi ceModel .ServerTooBusyException 

* 

* Rather than handling all of these the approach taken 

* is to recreate the proxy 

* object for all exception except for ones that are 

* explicitly known to be safe 
*/ 

if(!(e is FaultException) || serviceClient.InnerChannel .State 

. Equal s (Communi cati onState . Faulted)) 

{ 

serviced ient. Abort () ; 
serviced ient = null; 

} 

throw; 

} 

} 

} 


The first thing the method does is take a lock on the proxyLock object to ensure that this 
thread is the only one accessing the static serviceClient object. If the serviceClient is null, a 
new serviceClient is constructed and assigned to the static variable, as shown in 
Example 7-11. 

Example 7-11 Constructing the WCF proxy object 

if (serviceClient == null) 

{ 

serviceClient = new Cl aimsProcessingWcfServi ceCl ient () ; 

} 


The serviceClient can be null for one of two reasons: 

► This is the first time through the flow. 

► There is an exception that left the service proxy in an unusable state, and it needs to be 
recreated. 

After the service proxy is known to exist, the switch statement simply casts the request 
parameter based on the ClaimsProcessingRequest.TypeOfRequest field. This allows the 
code to know that the operation must be invoked on the serviceClient. 

The code also checks that the underlying communication channel owned by the serviceClient 
did not enter the Faulted state. This can happen if the session times out or there is some 
other issue with connectivity while the flow is waiting for a message. 
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For example, if the request received has a TypeOfRequest value of RequestType.ViewPolicy, 
the request is cast to a ViewPolicyRequest object, and then the serviceClient’s ViewPolicy 
method is invoked, as shown in the code in Example 7-12. 

Example 7-12 Making the WCF invocation 
case RequestType.ViewPolicy: 

response=servi ceCl ient. ViewPol i cy ( (ViewPol i cyRequest) request) ; 
break; 


The call serviceClient.ViewPolicy() causes the WCF framework to serialize the data held in 
the request parameter and send it using TCP/IP to the service. The service then executes its 
ViewPolicyO method that reads the data from the file system and then serializes the response 
message with the DataContractSerializer to send back over the wire to the serviceClient. 

The result is that after the call to serviceClient. ViewPolicyO completes, the request variable 
holds a ViewPolicyResponse object containing the policy details returned from the WCF 
Service. Note that although response was declared to be of type 

ClaimsProcessingResponse, the ViewPolicyResponse object derives from this base class. To 
access any fields specific to the ViewPolicyResponse class, the calling code must cast the 
response back to the correct type. 

In the default case where we are unable to identify the correct derived class based on the 
value of the TypeOfRequest field, an NBRecoverableException is thrown to return a 
meaningful error message to the caller. 


7.5.5 Handling exceptions when invoking the WCF service 

It is possible for the invocation of the service to fail, and the calling code must be prepared to 
deal with the failure gracefully. WCF failures can be due to either an exception encountered 
by the WCF service or exceptions caused by the underlying communications framework. 

In all cases where the remote WCF service experiences an exception, the exception is 
wrapped in a FaultException when it is presented to the client. These FaultException objects 
can be grouped into two main types: 

► FaultExceptions that are part of the declared Fault Contract 

► Unexpected FaultExceptions 

In the Fault Contract for the ClaimsProcessingWcfService, we defined two types of Fault in 
the Fault Contract, the ClaimsProcessingFault and the 

ViewOutstandingClaimsIncompleteResultsFault. By declaring these as part of the Fault 
Contract, we make the assertion that the client code knows about these Fault types and can 
take appropriate action. 

If the Fault received is part of the fault contract, the underlying communication channel does 
not enter the faulted state, and it is possible to reuse the serviceClient. In general, take care 
when reusing WCF proxy objects when a Fault occurred because the state on the remote 
server might not be consistent. Some channels will, for example, close a session on receipt of 
a fault, which can lead to application code mistakenly trying to reuse the service, assuming 
the session is still valid. 

For the example service, the service recovers from all ClaimsProcessingFault’s, and there is 
no stateful information stored in the service itself (because the state is stored on the file 
system). For this reason it is safe to reuse the serviceClient in any case where the underlying 
communications channel is not in the faulted state. 


Chapter 7. Scenario: Integrating Windows Communication Foundation in message flows - Part 2 307 





Unexpected FaultExceptions are the result of the remote WCF service encountering a 
managed exception that is not handled. In a production environment, a generic 
FaultException is returned; however, during development of an application, it can be useful to 
be able to see the details of these exceptions from the client. To enable this behavior, the 
App.Config of the WCF service can be updated with the following line: 

<servi ceDebug i ncl udeExcepti onDetai 1 InFaul ts="true"/> 

It is also possible for the WCF framework itself to throw a number of exceptions derived from 
the System. Model. CommunicationException and System.TimeoutException base classes. 
These exceptions indicate some underlying problem with the network transport, such as for 
example, if the network cable is unplugged from the machine. In these cases, the 
serviceClient needs to be recreated. 

The error handling in the CallClaimsProcessingService method has only the scope to handle 
the cleaning up of the serviceClient, if appropriate. The base type Exception is caught, and 
then the exception is tested to see if the serviceClient needs recreated. For the purposes of 
this example, we assume that any FaultException is safe unless the underlying 
communication channel is in the Faulted state. If the serviceClient needs to be recreated, the 
Abort() method is called to release local resources and transition the wcf proxy object to the 
closed state. As shown in Example 7-13, the serviceClient variable is then set to null so that 
the next invocation of the CallClaimsProcessingService will recreate the client. 

Example 7-13 The catch block in CallClaimsProcessingService controls when the serviceClient object 
is recreated 


catch(Exception e) 

{ 

/* WCF can cause the following exceptions: 

* System.TimeoutException 

* System. Servi ceModel .CommunicationException 

* System. Servi ceModel . AddressAl readylnUseExcepti on 

* System. Servi ceModel . AddressAccessDeniedException 

* System. Servi ceModel .CommunicationObjectFaultedException 

* System. Servi ceModel .CommunicationObjectAbortedException 

* System. Servi ceModel . EndpointNotFoundException 

* System. Servi ceModel . Protocol Excepti on 

* System. Servi ceModel .ServerTooBusyException 

* 

* Rather than handling all of these the approach 

* taken is to recreate the proxy 

* object for all exception except for ones that are 

* explicitly known to be safe 
*/ 

if(!(e is FaultException) || 

serviced ient. InnerChannel . State. Equal s(Communi cat ionState. Faulted)) 

{ 

serviced ient.AbortQ ; 
serviceClient = null ; 

} 

throw; 

} 


We will see in 7.5.13, “Handling FaultExceptions in the Evaluate() method” on page 321 that 
the known FaultException types that are part of the Fault Contract will cause different 
behavior of the Cal 1 WCFNode . eval uate () method. 
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7.5.6 Ensuring that the serviceClient is closed on flow deletion 


A WCF proxy that is not closed might be holding resources open on the service, so it is 
essential to ensure that when an application is finished with the serviceClient, its Close() 
method is called. The generated proxy is derived from ClientBase that ultimately implements 
the I Disposable interface, ensuring that when an object is destroyed, the Close() method is 
called. The only problem is that the Close() method itself can cause an exception because it 
requires a network round trip to the service to inform it to release any resources held open by 
the client. 

If there is a communications failure when the object is disposed of, this can lead to the 
finalizer for the node throwing an exception. To prevent this, the CallWCFNode should call the 
Close() method itself inside a try/catch block. If an exception occurs when trying to close the 
serviceClient, the Abort() method is called instead. 

The Abort() method, in contrast to the Close() method, causes the underlying object to move 
immediately to a closed state and any local resources released without making a network call 
to the client. 

The CallWCFNode overrides the onDelete() method that is called by the Broker node 
framework when a flow is not yet deployed to ensure that either the Close() or the Abort() 
method is called before the instance of the node is destroyed: 

Add the code shown in Example 7-14 to the class definition for CallWCFNode. 

Example 7-14 Overriding NBComputeNode.OnDelete() to ensure the serviceClient is closed 

public override void OnDeleteQ 

{ 

//ensure we close the serviceClient 
lock (proxyLock) 

{ 

if (serviceClient != null) 

{ 

try 

{ 

serviceClient.Close() ; 
serviceClient = null ; 

} 

catch (Exception) 

{ 

serviced ient. Abort () ; 
serviceClient = null ; 

} 

} 

} 

} 


7.5.7 Creating methods to add datatypes to the message tree 

To simplify the creation of the response messages in the message tree, the node has a 
number of helper methods for creating the main datatypes in the tree. These methods called 
AddClaimElementToParentO, AddPolicyElementToParent(), AddCustomerElementToParent() 
and AddPaymentElementToParent() all follow a similar implementation pattern. 
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1. Add the AddCustomerElementToParent() method shown in Example 7-15 to the class 
definition for CallWCFNode. 

Example 7-15 The AddCustomerElementToParent method in CallWCFNode.es 

private void AddCustomerElementToParent (Customer customer, NBElement parent, 

string tagName = "Customer") 

{ 

NBElement customerEl ement = parent. CreateLastChi ld(tagName) ; 
customer El ement .CreateLastChi 1 d ("Customer Id") .SetVal ue (customer. Customer Id) ; 
customerEl ement .CreateLastChi Id ("Fi rstName") .SetVal ue (customer. Fi rstName) ; 
NBElement otherNamesEl ement = customerEl ement .CreateLastChi 1 d("OtherNames") ; 
foreach (string name in customer. OtherNames) 

{ 

otherNamesEl ement. CreateLastChi ld("Name") .SetVal ue(name) ; 

} 

customerEl ement .CreateLastChi 1 d ("Surname") .SetVal ue (customer. Surname) ; 
customerEl ement .CreateLastChi 1 d ("Address") .SetVal ue (customer. Address) ; 
customerEl ement .CreateLastChi Id ("Emai 1 ") .SetVal ue (customer. Emai 1 ) ; 


This method takes a Customer object, such as one that might have been returned by an 
invocation to the WCF service, and creates a new element as a child of the parent 
parameter with a tree-based representation of this customer. The final parameter allows 
the parent tag name to be set, which defaults to the name of the class. 

The method uses the standard tree manipulation methods, NBEIement.CreateLastChild() 
and NBEIement.SetValueQ. 


Note: The Customer, Claim, InsurancePolicy, and Payment types are able to be 
serialized with an XMLSerializer, as you saw in 6.3.5, “Creating private methods to 
serialize and deserialize the Datatypes” on page 180. We can therefore also have used 
the NBEIement.CreateLastChildFromBitStream() method. The XML created by the 
XMLSerializer is not quite in the right format; however, some transformation is still 
needed. 


2. Implement the other three helper methods by adding the code shown in Example 7-1 6 to 
the CallWCFNode class definition. 

Example 7-16 Add the other 3 helper methods to CallWCFNode.es 

private void AddPaymentElementToParent (Payment payment, NBElement parent, 

string tagName = "Payment") 

{ 

NBElement paymentEl ement = parent.CreateLastChild(tagName) ; 
paymentEl ement. CreateLastChi ld("Amount") .SetVal ue(payment .Amount) ; 

AddCustomerEl ementToParent (payment . Payee, paymentEl ement) ; 

paymentEl ement. CreateLastChi ld("Underwri ter") .SetVal ue(payment .Underwri ter) ; 


private void AddPol icyEl ementToParent (InsurancePol icy policy, 

NBElement parent, string tagName = "Policy") 

{ 

NBElement pol i cyEl ement = parent. CreateLastChi ld(tagName) ; 

pol i cyEl ement .CreateLastChi 1 d("Pol i cyNumber") .SetVal ue(pol i cy. Pol i cyNumber) ; 

AddCustomerEl ementToParent (pol icy. Pol icyholder, pol icyEl ement, 

"Pol i cyHol der") ; 
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NBElement namedPartiesEl ement = pol icyEl ement .CreateLastChi 1 d( M NamedParties") ; 
foreach (Customer customer in pol icy.NamedParties) 


{ 

AddCustomerEl ementToParent (customer, namedPartiesEl ement) ; 

} 

pol i cyEl ement .CreateLastChi 1 d ( 11 Pol i cyCover 11 ) . SetVal ue (pol i cy . Pol i cyCover) ; 
pol icy El ement .CreateLastChi Id ("Pol icy Excess") .SetVal ue (pol icy. Pol icy Excess) ; 
pol i cyEl ement .CreateLastChi 1 d ( 11 Pol i cyExpi ryDate") .SetVal ue( 

pol icy. Pol i cyExpi ryDate) ; 

pol i cyEl ement .CreateLastChi 1 d ( 11 Pol i cyName") .SetVal ue(pol i cy. Pol i cyName) ; 
pol i cyEl ement .CreateLastChi 1 d("Pol i cyStartDate") .SetVal ue( 

pol icy. Pol i cyStartDate) ; 

pol i cyEl ement .CreateLastChi 1 d("Underwri ter") .SetVal ue(pol i cy .Underwri ter) ; 

} 


private 

{ 


void AddCl aimEl ementToParent (Cl aim claim, NBElement parent, 

string tagName = "Claim") 


NBElement claimElement = parent. CreateLastChi 1 d(tagName) ; 

cl aimEl ement .CreateLastChi Id ("Cl aimDate") .SetVal ue(cl aim. Cl aimDate) ; 

cl aimEl ement .CreateLastChi Id ("Cl aimRecei vedDate") .SetVal ue( 

cl aim. Cl aimRecei vedDate) ; 

cl aimEl ement .CreateLastChi Id ("Cl aimReference") .SetVal ue (cl aim. Cl aimReference) ; 

cl aimEl ement. CreateLastChi Id ("Cl aimVal ue") .SetVal ue(claim.Cl aimVal ue) ; 

AddCustomerEl ementToParent (cl aim. Customer, cl aimEl ement) ; 

cl aimEl ement .CreateLastChi Id ("Descri ption") .SetVal ue(cl aim.Descri pti on) ; 

cl aimEl ement .CreateLastChi Id ("Notes") .SetVal ue(cl aim. Notes) ; 

cl aimEl ement .CreateLastChi Id ("Pol icyNumber") .SetVal ue(cl aim. Pol i cyNumber) ; 

cl aimEl ement. CreateLastChi Id ("Status") .SetVal ue(cl aim. Status) ; 


7.5.8 Creating a helper method to build Customer object from the Logical 
Message Tree 

The Customer datatype is used in the parameters for several of the request operations in this 
scenario. We therefore create a helper method that is responsible for taking an NBElement in 
the tree and converting this into a .NET Customer object that can be used to construct the 
data used making the WCF Service invocation. 

1 . Add the method shown Example 7-1 7 in to Cal 1 WCFNode . cs. 

Example 7-17 The CreateCustomerFromElement method in CallWCFNode.es 

private Customer CreateCustomerFromElement (NBElement customerEl ement) 

{ 

Customer customer = new CustomerQ; 

customer. Customerld = customerEl ement ["Customerld"] . Val ueAsString; 
customer. Fi rstName = customerEl ement ["Fi rstName"] .Val ueAsString; 

NBElement otherNamesEl ement = customerEl ement ["OtherNames"] ; 

string [] otherNamesArray = new stri ng [otherNamesEl ement. Chi ldren() .Count ()] ; 

for (int i = 0; i < otherNamesEl ement. Chi ldren() .Count () ; i++) 

{ 

otherNamesArray [i] = 

otherNamesEl ement .Chi ldren() . ElementAt (i ) .Val ueAsStri ng; 

} 

customer. OtherNames = otherNamesArray; 

customer. Surname = customerEl ement ["Surname"] .Val ueAsString; 
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customer. Emai 1 = customerElement["Email "] . Val ueAsString; 
return customer; 


Note: The NBEIement.Children() method returns an Enumerable, so we can use a 
method like Count() or the for-each construct. In this instance, a plain for loop is used 
because we need to index into the otherNamesArray. 


7.5.9 Preparing the ClaimsProcessingRequest object 

The pattern of execution that is used in the main body of the Evaluate() method is to first 
locate the appropriate fields in the message tree to be used to make the request, and then 
convert the data in the logical message tree into an appropriate derived class of 
ClaimsProcessingRequest. 

This request object is then used to make the WCF invocation using the 
CallClaimsProcessingService() method. The returned response is then converted from a 
.NET object into a message tree for propagation to the of the flow. 

To simplify the evaluate method, the preparation of the request object is managed by a single 
call to the PrepareRequest() method. This method uses a switch statement to delegate to the 
appropriately overloaded form of the method that corresponds to the type of request being 
processed: 

1. Add the code shown in Example 7-18 to the CallWCFNode class definition. 

Example 7-18 The PrepareRequest method in CallWCFNode. cs 

private void PrepareRequest (Cl aimsProcessingRequest request, NBElement requestElement) 

{ 

swi tch (request . TypeOf Request) 

{ 

case RequestType. Approved aim: 

PrepareRequest ( (Approved aimRequest) request, requestElement); 
break; 

case RequestType. CreatePol i cy: 

PrepareRequest ( (CreatePol i cyRequest) request , requestEl ement) ; 
break; 

case RequestType. NewCl aim: 

PrepareRequest ((NewCl aimRequest) request, requestElement) ; 
break; 

case RequestType. RejectCl aim: 

PrepareRequest ((RejectCl aimRequest) request, requestElement) ; 
break; 

case RequestType. ViewClaim: 

PrepareRequest ( (Vi ewCl aimRequest) request , requestEl ement) ; 
break; 

case RequestType. ViewOutstandi ngCl aims : 

PrepareRequest ((Vi ewOut standi ngCl aims Request) request, requestElement) ; 
break; 

case RequestType. Vi ewPol icy: 

PrepareRequest ( (Vi ewPol i cyRequest) request, requestElement) ; 
break; 
default: 

throw new Inval idOperationExcepti on ("Generic request not possible!"); 


} 
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The switch statement operates on the TypeOfRequest field of the request parameter. Note 
that if the type of request is not recognized, an InvalidOperation is thrown. 

2. Each of the specific PrepareRequest methods follows a similar pattern. Add the method 
shown in Example 7-19 to the CallWCFNode class definition. 

Example 7-19 The PrepareRequest() method for CreatePolicyRequest message type in 
CallWCFNode.es 


private void PrepareRequest (CreatePol icyRequest request, NBElement requestElement) 

{ 

request . PrimaryCustomer = 

CreateCustomerFromElement (requestEl ement ["PrimaryCustomer"] ) ; 
IEnumerable<NBElement> namedParti esEl ements = 

requestElement ["NamedParties"] .Chi ldren() ; 
Customer[] namedParties = new Customer[namedPartiesElements.Count()] ; 
for (int i =0; i < namedPart ies. Count () ; i++) 

{ 

namedParti es[i] = 

CreateCustomerFromEl ement (namedParti esEl ements . El ementAt (i ) ) ; 

} 

request. NamedParties = namedParties; 

request. Pol icyName = requestElement ["Pol icyName"] . Val ueAsString; 
request. Pol icyCover = requestElement["Pol icyCover"] .Getlnt32() ; 
request. Pol icy Excess = requestElement ["Pol icy Excess"] .Getlnt32() ; 


The requestElement parameter passed in is expected to correspond to the 
CanonicalMessage/ApplicationMessage/ClaimsProcessingRequest/CreatePolicyRequest 
element in the logical tree. 

This method uses array syntax to reference message tree elements in the requestElement 
argument and uses these values to set corresponding fields in the CreatePolicyObject 
.NET object. Note that for types that are not strings, the appropriate method is called on 
the referenced element to get the value as the correct datatype. 

3. To implement the remaining PrepareRequest() methods for the other types of requests, 
add the following code to the CallWCFNode class definition. 

Example 7-20 The remaining PrepareRequestQ methods in CallWCFNode.es 


private void PrepareRequest (Approved aimRequest request, NBElement requestElement) 

{ 

request .AgentReference = requestElement ["AgentReference"] .Val ueAsString; 
request .Cl aimReference = requestElement["ClaimReference"] .Val ueAsString; 
request .Val ueApproved = requestEl ement ["Val ueApproved"] .Getlnt32() ; 

} 

private void PrepareRequest (NewCl aimRequest request, NBElement requestElement) 

{ 


NBElement claimElement = requestElement ["NewCl aim"] ; 

Claim claim = new ClaimQ; 

cl aim. Cl aimDate = claimElement["ClaimDate"] .GetDateTime() ; 
cl aim. Cl aimRecei vedDate = DateTime.Now; 

cl aim. Cl aimReference = claimElement ["Cl aimReference"] .Val uelsNul 1 ? 

null : cl aimEl ement ["Cl aimReference"] .Val ueAsString; 
cl aim. Cl aimVal ue = cl aimEl ement ["Cl aimVal ue"] .Getlnt32() ; 
cl aim. Customer = CreateCustomerFromEl ement (cl aimEl ement ["Customer"] ) ; 
cl aim. Description = cl aimElement ["Description"] .Val ueAsString; 
claim. Notes = claimElement ["Notes"] .Val ueAsString; 
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cl aim. Pol icyNumber = cl aimEl ement ["Pol icyNumber 11 ] .Val ueAsString; 
claim. Status = Cl aimState.Submi tted; 
request .NewCl aim = claim; 

} 

private void PrepareRequest (RejectCl aimRequest request, NBElement requestEl ement) 

{ 

request .AgentReference = requestEl ement ["AgentReference"] .Val ueAsString; 
request .ClaimReference = requestElement["ClaimReference M ] .Val ueAsString; 
request .Reason = requestEl ement ["Reason"] .Val ueAsStri ng; 

} 

private void PrepareRequest (Vi ewCl aimRequest request, NBElement requestEl ement) 

{ 

request .ClaimReference = requestElement["ClaimReference"] .Val ueAsString; 

} 

private void PrepareRequest (Vi ewOutstandi ngCl aimsRequest request, 

NBElement requestEl ement) 

{ 

//This request type has no additional properties 
return; 


private void PrepareRequest (ViewPol icyRequest request, NBElement requestEl ement) 

{ 

request . Pol i cyReference = requestEl ement ["Pol i cyReference"] .Val ueAsStri ng; 

} 


Note that the ViewOutstandingClaimsRequest does not provide any additional parameters 
over the base type of ClaimsProcessingRequest, so the PrepareRequest() message for this 
message type does not do anything. 

The calling code is expected to set the fields defined by the base ClaimsProcessingRequest 
type, which is done in the Evaluate method with the code shown in Example 7-21 . 

Example 7-21 Setting the properties on the ClaimsProcessingRequest base type 

//All requests share some common properties 
request. Appl icationld = headerEl ement ["Appld"] .Val ueAsStri ng; 
request .Messageld = headerElement["MsgId 11 ] .Val ueAsStri ng; 
request. RequestDate = requestedDate; 


7.5.10 Adding the information from the WCF response into the message tree 

After a request is made to the WCF service, the data contained in the 
ClaimsProcessingRequest needs to be added to the tree. To keep message type-specific 
processing out of the main line of the Evaluate() method, this is handled by a single 
AddResponseDataToTree that takes a ClaimsProcessingRequest and adds the data to the 
provided responseElement in the tree. This general method delegates to a specific 
overridden method based on the TypeOfResponse field: 

1 . Add the code shown in Example 7-22 to the class declaration for CallWCFNode. 

Example 7-22 The AddResponseDataToTree method delegates based on the TypeOfRequest 

private void AddResponseDataToTreefClaimsProcessingResponse response, 

NBElement responseElement) 
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{ 

swi tch (response. TypeOfResponse) 

{ 

case ResponseType. Approved aim: 

AddResponseDataToTree( (Approved aimResponse) response, 
responseEl ement) ; 

break; 

case ResponseType. CreatePol icy: 

AddResponseDataToTree((CreatePol i cyResponse) response, 
responseEl ement) ; 

break; 

case ResponseType. NewCl aim: 

AddResponseDataToTree( (NewCl aimResponse) response, 
responseEl ement) ; 

break; 

case ResponseType. RejectClaim: 

AddResponseDataToTree( (RejectCl aimResponse) response, 
responseEl ement) ; 

break; 

case ResponseType. Vi ewCl aim: 

AddResponseDataToTree((Vi ewCl aimResponse) response, 
responseEl ement) ; 

break; 

case ResponseType. Vi ewOutstandi ngClaims: 

AddResponseDataToTree((Vi ewOutstandi ngCl aimsResponse) response, 
responseEl ement) ; 

break; 

case ResponseType. Vi ewPol icy: 

AddResponseDataToTree((ViewPol i cyResponse) response, 
responseEl ement) ; 

break; 

default: 

throw new Inval idOperationException( 

"Generic request not possible!"); 


The specific methods use the methods defined earlier in this section to add various data 
types to the tree. In some cases, there is no response data that is specific to the type of 
response, so in this instance only, the root element of the response is created. 

2. Add the specific AddResponseDataToTree() methods shown in Example 7-23 to the class 
declaration for CallWCFNode. 

Example 7-23 Response type specific versions of AddResponseDataToTree() 

private void AddResponseDataToTree(ApproveCl aimResponse response, 

NBE1 ement responseEl ement) 

{ 

NBE1 ement approved aimResponseEl ement = responseEl ement 
. CreateLastChi 1 d ("Approved aimResponse") ; 

AddPaymentEl ementToParent (response. Payment, approved aimResponseEl ement) ; 


private void AddResponseDataToTree(CreatePol i cyResponse response, 

NBE1 ement responseEl ement) 

{ 

NBE1 ement createPol i cyResponseEl ement = responseEl ement 
.CreateLastChi 1 d(" CreatePol i cyResponse") ; 

AddPol icyEl ementToParent (response. Pol icy, createPol i cyResponseEl ement) ; 
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} 


private void AddResponseDataToTree(NewCl aimResponse response, 
NBElement responseEl ement) 

{ 

responseEl ement. CreateLastChi 1 d("NewCl aimResponse") ; 

//No additional properties for this response type 


private void AddResponseDataToTree(ViewClaimResponse response, 
NBElement responseEl ement) 

{ 

NBElement vi ewCl aimResponseEl ement = responseEl ement 
. CreateLastChi 1 d ("Vi ewCl aimResponse") ; 
AddClaimElementToParent (response. Cl aim, viewCl aimResponseEl ement) ; 


private void AddResponseDataToTree(ViewPolicyResponse response, 
NBElement responseEl ement) 

{ 

NBElement vi ewPol i cyResponseEl ement = responseEl ement 
. CreateLastChi 1 d (" Vi ewPol i cyResponse") ; 

AddPol i cyEl ementToParent (response . Pol i cy , 
vi ewPol i cyResponseEl ement , 

"Policy"); 


} 

private void AddResponseDataToTree(RejectCl aimResponse response, 
NBElement responseEl ement) 

{ 

responseEl ement. CreateLastChi 1 d("RejectCl aimResponse") ; 

//No additional properties for this response type 


private void AddResponseDataToTree(ViewOutstandingClaimsResponse response, 
NBElement responseEl ement) 

{ 

NBElement outstandi ngCl aimsEl ement = responseEl ement 
. CreateLastChi 1 d ("Vi ewOutstandi ngCl aimsResponse") 

.CreateLastChi 1 d(" Out standi ngCl aims") ; 
foreach (Claim claim in response. OutstandingClaims) 

{ 

AddCl aimEl ementToParent (cl aim, outstandi ngCl aims El ement) ; 

} 


7.5.11 The CallWCFNode.EvaluateO method 

The Evaluate method of the CallWCFNode class is invoked by the WebSphere Message 
Broker node framework when execution reaches the input terminal of the corresponding 
.NETCompute node in the message flow. 
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This is the main entry point into the node and the main job of this method is to locate the 
information in the tree that is required to build the ClaimsProcessingRequest message, call 
the helper method CallClaimsProcessingService to make the WCF invocation, and finally put 
the details from the returned ClaimsProcessingResponse object into the message tree. 

The Add Class Wizard generates skeleton code needed to access the input and output 
message tree, so the Evaluate method is implemented by filling in the UserCode #region 
block provided: 

1 . Add the code shown in Example 7-24 to the Evaluate() method inside the UserCode 
#region. 

Example 7-24 Evaluate() method part 1 in CallWCFNode.es 
Iregion UserCode 

//set these flags so that the error handler can tell where any tree navigations //failed 
bool canonicalMessageMatched = false; 
bool recognisedApplicationMessage = false; 
bool requestParametersFound = false; 
try 
{ 

NBElement canonicalMessagelnputElement = 

inputRoot["XMLNSC"] [Constants. cp, "CanonicalMessage"] ; 
NBElement headerElement = canonicalMessageInputElement["Header"] ; 

canonicalMessageMatched = true; 


The method starts by declaring some boolean values to use as flags so that we can detect 
when tree navigation failed to convert the resulting NullReferenceException into a 
meaningful error message. The first of these flag variables, canonicalMessageMatched, is 
set to true after we verify that the input message is a CanonicalMessage. Note the use of 
Constants.cp to reference the CanonicalMessage namespace. 

Next, the specific request element is found in the logical message tree from the 
CanonicalMessage\ApplicationMessage\ClaimsProcessingRequest path. The name of 
the last child of the ClaimsProcessingRequest element is used in a switch statement to 
create an appropriately typed ClaimsProcessingRequest and the results assigned to the 
pre-declared base class variable ClaimsProcessingRequest. 

Since in WCF constructors are not run on serialization and de-serialization of Data 
Contract types, the svcutil generated classes do not set the TypeOfRequest field in the 
constructor. Further the generated class actually treats this read only field as a normal 
field, as you can see by examining the generated code in ClaimsProcessingWcfService.es 
shown in Example 7-25. 

Example 7-25 Generated code for ClaimsProcessingRequest 

[System. Runtime. Seri al i zati on . DataMemberAttri bute ( ) ] 
public I bm. Broker. Example. Cl aimsProcessi ng.RequestType TypeOfRequest 
{ 

get 

{ 

return thi s . TypeOfRequest Fi eld; 

} 

set 

{ 

this.TypeOfRequestField = value; 

} 
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This means that when we create the derived class for ClaimsProcessingRequest, we also 
need to set the TypeOfRequest filed so that subsequent code operating on the object can 
determine the request type without needing to use reflection. 

2. Add the code shown in Example 7-26 to the UserCode region of the Evaluate() method 
(directly below the code in Example 7-24 on page 317) to implement this switch 
statement. 


Example 7-26 Evaluate() method part 2 in CallWCFNode.es 
NBElement applicationMessagelnputElement = 

canoni cal Message Input El ement [ 11 Appl i cat ionMes sage"] ; 

NBElement requestEl ement = 

appl i cati onMessage Input El ement [ 11 Cl aimsProcessi ngRequest"] . LastChi Id; 


//Create the appropriate type of request 
Cl aimsProcessi ngRequest request; 
swi tch (requestEl ement. Name) 

{ 


} 


case "Approved aimRequest" : 

request = new ApproveClaimRequestQ ; 

request .TypeOfRequest = RequestType.ApproveClaim; 

break; 

case "CreatePol i cyRequest" : 

request = new CreatePol i cyRequest () ; 

request .TypeOfRequest = RequestType. CreatePol i cy; 

break; 

case "NewCl aimRequest" : 

request = new NewCl aimRequest () ; 

request .TypeOfRequest = RequestType. NewClaim; 

break; 

case "RejectCl aimRequest" : 

request = new RejectCl aimRequest () ; 

request .TypeOfRequest = RequestType. RejectCl aim; 

break; 

case "Vi ewCl aimRequest" : 

request = new Vi ewCl aimRequest () ; 

request. TypeOfRequest = RequestType. ViewClaim; 

break; 

case "Vi ewOutstandi ngCl aimsRequest" : 

request = new ViewOutstandingClaimsRequest() ; 

request. TypeOfRequest = RequestType. ViewOutstandingClaims; 

break; 

case "Vi ewPoli cyRequest" : 

request = new Vi ewPol i cyRequest () ; 

request .TypeOfRequest = RequestType. ViewPol icy; 

break; 

default: 

throw new NBRecoverabl eExcepti on ("Unrecogni sed Request type " + 

requestElement.Name) ; 


//this is a message type the flow knows about 
recogni sedAppl i cati onMessage = true; 
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If the tree references complete successfully and the first child of the 
ClaimsProcessingRequest element is a type of request that the flow recognizes, the 
boolean flag is set to indicate that the ApplicationMessage was successfully recognized. 

3. Add the code shown in Example 7-27 to the UserCode region in the Evaluate()method 
directly below the code in Example 7-26 on page 318. 

Example 7-27 Evaluate() method part 3 in CallWCFNode.cst 

//All requests share some common properties 

request . Appl i cati on Id = headerEl ement ["Appld"] . Val ueAsStri ng; 

request. Messageld = headerElement["MsgId"] .Val ueAsStri ng; 

DateTime requestedDate = requestElement["RequestedDate"] .GetDateTime() ; 
request. RequestDate = requestedDate; 


The ClaimsProcessingRequest base class defines some fields that are common across all 
requests. The code in Example 7-27 fills in these values from the request variable (that 
remember is typed to refer to the ClaimsProcessingRequest base class) by locating the 
Appld, Msgld, and RequestedDate from the logical message tree. 

The next code segment is where most of the actual work in this node takes place. Recall 
that we defined three helper methods to populate the request object based on its type, 
make the WCF request, and the populate the message tree based on the response. 
These methods are now called from the Evaluate() method, as shown in Example 7-28. 
Implementing these methods means we avoided including a large amount of 
message-specific code in the Evaluate() method itself. 

4. Add the following code to the UserCode region in the Evaluate() method. 

Example 7-28 Evaluate() method part 4 in CallWCFNode.es 

//call overloaded method to fill in properties specific to each 
//request type 

PrepareRequest(request, requestEl ement) ; 
requestParametersFound = true; 

Cl aimsProcessingResponse response = CallClaimsProcessingService(request) ; 

NBE1 ement appl i cati onMessageOutputEl ement = outputRoot["XMLNSC"] 

[Constants. cp, "CanonicalMessage"] ["ApplicationMessage"] ; 
appl i cati onMessageOutputEl ement. Del eteAl IChi ldren() ; 

NBElement claimsProcessingResponseOutputElement = 

appl i cati onMessageOutputEl ement . CreateLastChi 1 d ( "Cl aimsProcessingResponse") ; 
AddResponseDataToTree (response, claimsProcessi ngResponseOutputEl ement) ; 


Note: The requestParameterFound flag is set to true if the PrepareRequest method 
completes successfully. The PrepareRequest method performs a substantial amount of 
tree navigation using the array syntax so that it can populate the request object. 
NullReferenceException, thrown within this method, is caught in the catch block for the 
Evaluate() method. 


The AddResponseDataToTree needs an NBelement passed in as a parameter to which to 
attach the request data. This is created by deleting all children of the ApplicationMessage 
element and then using NBEIement.Createl_astChild() to create the 
ClaimsProcessingResponse element. 

After the response data is populated into the logical message tree, there are several fields 
that are common across all responses that are populated by the EvaluateQ method. The 
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NBBroker class is used to obtain runtime information about the broker and the flow to fill in 
the LastModifiedBy field of the trailer. 

Finally, the message is propagated to the Out terminal. Note that the propagate statement 
is moved inside the userCode #region block because all code paths from our catch blocks 
end up exiting using the throw. 

5. Add the code shown in Example 7-29 to the UserCode region in the Evaluate() method. 

Example 7-29 Evaluate () method part 5 in CallWCFNode.es 

NBElement i nnerResponseEl emement = 

cl ai ms Process i ngResponseOutputEl ement . Fi rstChi 1 d ; 
i nnerResponseEl emement .CreateFi rstChi Id ("Correl Id") 

.SetVal lie (response. Correl at i on Id) ; 
i nnerResponseEl emement .CreateLastChi 1 d("ResponseTime") 

.SetVal lie (response. ResponseTi me) ; 


//Set the trailer information 

outputRoot ["XMLNSC"] [Constants .cp, "CanonicalMessage"] ["Trailer"] 

["LastModi fi ed"] .SetVal ue(DateTime.Now) ; 
outputRoot ["XMLNSC"] [Constants .cp, "CanonicalMessage"] ["Trailer"] 

["LastModifiedBy"] .SetVal ue("WebSphere Message Broker " + 
NBBroker. Broker. BrokerVersion + 11 - 11 + 

NBBroker. Broker. Name + "." + NBMessageFl ow.MessageFl ow. Name) ; 

// Change the following if not propagating message to the 'Out' terminal 
outTermi nal .Propagate(outAssembly) ; 


7.5.12 Handling failed tree navigations in the Evaluate() method 

If any of the tree navigation fails in the Evaluate() method or any of the called methods, the 
result is a NullReference exception. The first catch block in the Evaluate() method checks the 
boolean flags that are set as execution proceeded through the Evaluate^) method to convert 
the NRE in to a meaningful NBRecoverableException that explains that the content of the 
message did not match the expected structure: 

1 . Add the catch block shown in Example 7-30 to the UserCode region of the Evaluate() 
method. 

Example 7-30 Evaluate() method part 6 in CallWCFNode.es 

catch (Nul 1 ReferenceException) 

{ 

//Some Nul 1 ReferenceException are generated due to a malformed input message, 

//test for cases where we want to raise an informative error for the user 
//throw other instances, 
if ( Icanoni calMessageMatched) 

{ 

throw new NBRecoverableException("Input not recognized by canonical message 
model. Root tag may be incorrect." + 

"Correct input and retry."); 

} 

else if (Irecogni sedAppl icationMessage) 

{ 

throw new NBRecoverableException("Input recognized as canonical " + 

"message but either the Appl icationMessage, " + 

"Cl aimsProcessi ngRequest or RequestedDate fields were not " + 

"found. Message may not be intended for this" + 
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application, check routing and content and retry. 11 ); 


} 

else if (IrequestParametersFound) 

{ 

throw new NBRecoverableException("One or more parameters for this" + 

"request were missing. Correct input and retry"); 

} 

//Any other NRE's are failure not due to navaigation of the tree 
throw; 


7.5.13 Handling FaultExceptions in the Evaluate() method 

The CallClaimsProcessing method throws FaultExceptions back to the calling code to handle. 
These FaultExceptions are caught in the Evaluate() method of the CallWCFNode. Recall from 
“Defining the Fault types” on page 208 that the Fault Contract of the WCF Service specifies 
that the calling code must be prepared to handle two types of Fault: ClaimsProcessingFaults 
and ViewOutstandingClaimsIncompleteResultsFault. 

Because ViewOutstandingClaimsIncompleteResultsFault is derived from 
ClaimProcessingFault, it needs to be caught first to provide unique handling for this fault type. 
The catch block for ClaimsProcessingFaults is listed second to catch Faults that are instances 
of the base class. Recall that these exceptions are wrapped in a FaultException object: 

1 . Add the code shown in Example 7-31 to the UserCode region of the Evaluate() method to 
implement both catch blocks. 

Example 7-31 EvaluateQ method part 7 in CallWCFNode.es 


catch (Faul t Except i on<Vi ewOutstandi ngCl aimslncompl eteResul tsFaul t> e) 

{ 

//Some clients are happy with incomplete results so 
//copy the results to the environment tree 
//before rethrowing 
NBElement errorsElement = 

i nputAssembly. Envi ronment .Root El ement .CreateLastChi Id ("Errors") ; 

NBElement claimsElement = errorsElement. CreateLastChild("OutstandingClaims") ; 
foreach (Claim claim in e. Detail .OutstandingResults) 

{ 

AddClaimElementToParent(claim, claimsElement) ; 

} 

NBElement errorDetai 1 sEl ement = errorsElement. CreateLastChild("ErrorList") ; 
foreach (ClaimProcessingFault fault in e. Detail .FaultList) 

{ 

errorDetailsElement.CreateLastChild("Fault") .SetValue(fault.ErrorCode + " + 

faul t. Message) ; 


} 

throw; 

} 

catch (FaultException<ClaimProcessingFault> e) 

{ 

throw new NBRecoverabl eExcepti on ( "CLAIMS PROCESSING FAULT. Code: " + 
e. Detail .ErrorCode + " ErrorText: " + e. Detail .Message) ; 

} 


As discussed in 7.8, “Processing incomplete results for the ViewOutstandingClaims 
operation” on page 333, ViewOutstandingClaimsIncompleteResultsFaults are used to 


Chapter 7. Scenario: Integrating Windows Communication Foundation in message flows - Part 2 321 




construct a list of the incomplete claims in the Environment tree so that it can be accessed by 
upstream nodes in the flow. 

ClaimsProcessingFaults are handled by extracting the ErrorCode and Message fields defined 
on the customer Fault type and then using these to construct a new NBRecoverableException 
that is thrown to be handled by the upstream flow. 


7.5.14 Verifying the completed CallWCFNode 

The Evaluate() method of the CallWCFNode is now complete, and the finished method is 
shown for reference in Example 7-32. 

Example 7-32 The completed Evaluate() method in CallWCFNode.es 

public override void Eval uate(NBMessageAssembly i nputAssembly) 

{ 

NBOutputTermi nal outTerminal = OutputTermi nal ("Out") ; 

NBMessage inputMessage = i nputAssembly. Message; 

// Create a new message from a copy of the inboundMessage, ensuring it is 
// disposed of after use 

using (NBMessage outputMessage = new NBMessage(inputMessage)) 

{ 

NBMessageAssembly outAssembly = 

new NBMessageAssembly (i nputAssembly, outputMessage); 

NBElement inputRoot = i nputMessage. RootEl ement ; 

NBElement outputRoot = outputMessage. RootEl ement; 

#region UserCode 

//set these flags so that the error handler can tell where any tree 
navigations failed 

bool canonicalMessageMatched = false; 
bool recognisedApplicationMessage = false; 
bool requestParametersFound = false; 
try 
{ 

NBElement canonicalMessagelnputElement = i nputRoot ["XMLNSC"] 
[Constants. cp, "CanonicalMessage"] ; 

NBElement headerEl ement = canonicalMessageInputElement[ l, Header M ] ; 


canonicalMessageMatched = true; 

NBElement appl icationMessagelnputElement = 
canoni cal Message Input El ement ["Appl i cat ionMes sage"] ; 

NBElement requestEl ement = appl icationMessagelnputElement 
["Cl aims Process i ngRequest"] . LastChi Id; 

//Create the appropriate type of request 
ClaimsProcessi ngRequest request; 
swi tch (requestEl ement . Name) 

{ 

case "Approved aimRequest": 
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request = new Approved aimRequest() ; 

request .TypeOfRequest = RequestType. Approved aim; 

break; 

case "CreatePol i cyRequest" : 

request = new CreatePol i cyRequest () ; 

request .TypeOfRequest = RequestType. CreatePol i cy; 

break; 

case "NewCl aimRequest" : 

request = new NewCl aimRequest () ; 

request .TypeOfRequest = RequestType. NewCl aim; 

break; 

case "RejectCl aimRequest" : 

request = new RejectClaimRequestQ ; 

request .TypeOfRequest = RequestType. RejectClaim; 

break; 

case "Vi ewCl aimRequest" : 

request = new ViewClaimRequest() ; 

request .TypeOfRequest = RequestType. Vi ewCl aim; 

break; 

case "Vi ewOutstandi ngCl aimsRequest" : 

request = new ViewOutstandingClaimsRequest() ; 

request .TypeOfRequest = RequestType. ViewOutstandingClaims; 

break; 

case "Vi ewPoli cyRequest" : 

request = new Vi ewPol i cyRequest () ; 

request .TypeOfRequest = RequestType. Vi ewPol i cy; 

break; 

default: 

throw new NBRecoverableException( 

"Unrecognised Request type " + requestElement.Name) ; 

} 

//this is a message type the flow knows about 
recogni sedAppl icationMessage = true; 

//All requests share some common properties 

request. Appl icationld = headerElement["AppId"] .ValueAsString; 

request. Messageld = headerEl ement ["Msgld"] . Val ueAsStri ng; 

DateTime requestedDate = requestElement["RequestedDate"] 
.GetDateTime() ; 

request. RequestDate = requestedDate; 

//call overloaded method to fill in properties specific to each 
// request type 

PrepareRequest (request, requestEl ement) ; 
requestParametersFound = true; 

ClaimsProcessingResponse response = 

Cal 1 Cl aimsProcessi ngServi ce (request) ; 

NBElement appl icationMessageOutputElement = outputRoot ["XMLNSC"] 
[Constants. cp, "CanonicalMessage"] ["Appl icationMessage"] ; 
appl i cati onMessageOutputEl ement .Del eteAl 1 Chi 1 dren () ; 

NBElement cl aimsProcessi ngResponseOutputEl ement = 
appl i cati onMessageOutputEl ement 
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.CreateLastChi 1 d ( " Cl aimsProcessi ngResponse") ; 


AddResponseDataToTree (response, 
cl aimsProcessi ngResponseOutputEl ement) ; 

NBElement i nnerResponseEl emement = 
cl aimsProcessi ngResponseOutputEl ement . Fi rstChi Id; 

i nnerResponseEl emement .CreateFi rstChi 1 d("Correl Id") 

.SetVal ue (response. Correl at ion Id) ; 

i nnerResponseEl emement .CreateLastChi 1 d("ResponseTime") 

.SetVal ue (response. ResponseTi me) ; 

//Set the trailer information 

outputRoot ["XMLNSC"] [Constants . cp, "CanonicalMessage"] ["Trailer"] 
["LastModi fi ed"] .SetVal ue(DateTime.Now) ; 

outputRoot ["XMLNSC"] [Constants . cp, "CanonicalMessage"] ["Trailer"] 
["LastModifiedBy"] .SetVal ue("WebSphere Message Broker " + 

NBBroker. Broker. BrokerVersi on + " - " + NBBroker. Broker. Name 
+ "." + NBMessageFlow.MessageFlow.Name) ; 

// Change the following if not propagating message to the 
// 'Out' terminal 

outTermi nal . Propagate(outAssembly) ; 

} 

catch (Nul 1 ReferenceExcepti on) 

{ 

//Some Nul 1 ReferenceExcepti on are generated due to a malformed 
// input message, 

//test for cases where we want to raise an informative error 
// for the user throw other instances, 
if (IcanonicalMessageMatched) 

{ 

throw new NBRecoverableException("Input not recognized by" + 
"canonical message model. Root tag may be " + 

"incorrect. Correct input and retry."); 

} 

else if (IrecognisedApplicationMessage) 

{ 

throw new NBRecoverableException("Input recognized as" + 
"canonical message but either the Appl icationMessage, " 

+ "Cl aimsProcessi ngRequest or RequestedDate fields " + 

"were not found. Message may not be intended for this" 

+ "application, check routing/content and retry."); 

} 

else if ( IrequestParametersFound) 

{ 

throw new NBRecoverableException("One or more parameters " + 

"for this request were missing. Correct input " + 

"and retry"); 

} 

//Any other NRE's are failure not due to navaigation of the tree 
throw; 

} 

catch (Faul t Except i on<Vi ewOut standi ngCl aimslncompl eteResul tsFaul t> e) 

{ 

//Some clients are happy with incomplete results so copy the results 
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// to the environment tree before rethrowing 

NBElement errorsEl ement = inputAssembly. Environment. RootElement 
.CreateLastChi 1 d(" Errors") ; 

NBElement cl aimsEl ement = errorsEl ement 
.CreateLastChi 1 d(" Out standi ngCl aims") ; 
foreach (Claim claim in e. Detail .Outstandi ngResul ts) 

{ 

AddCl aimEl ementToParent (cl aim, cl aims El ement) ; 

} 

NBElement errorDetai 1 sEl ement = errorsEl ement 
.CreateLastChi 1 d(" Error Li st") ; 
foreach (Cl aimProcessi ngFaul t fault in e. Detail .FaultList) 

{ 

errorDetai 1 sEl ement .CreateLastChi 1 d("Faul t") 
.SetValue(fault.ErrorCode + 11 + faul t. Message) ; 

} 

throw; 

} 

catch (FaultException<ClaimProcessingFaul t> e) 

{ 

throw new NBRecoverabl eExcepti on ( 11 CLAIMS PROCESSING FAULT. Code: " 
+ e. Detail .ErrorCode + 11 ErrorText: 11 + e. Detail .Message) ; 

} 

#endregion UserCode 

} 

} 


The last step is to update the properties for the CallWCFService node to point to the 
assembly and class, which we complete later in 7.13.1, “Building a solution” on page 358. 

This completes the implementation of the node itself. Now is a good opportunity to build the 
project using the Build -> Build Solution menu item in Visual Studio. A successful build 
shows output like the example in Figure 7-35. 


Output 


- ¥ X 


Show output from: Build 


3 1 I * I * I a 


Build started: Project: ClainsProcessingBrokerProjectj Con-figuration: Debug Any CPU 

Build started 27/03/2012 14:13:30. 

Ge ne rat eTargetFrameworkJtoni Ice rAt tribute : 

Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output -files are up-to-date with respect to the input fi] 
Co recompile : 

c : \WINDOW5\Microsoft . NET\Framework\v4 .0 . 30319\Csc . e&e /noconfig /nowarn : 1701,1702 /nostdlib+ /errorreport : prompt /warn: 4 /de-f 
_CopyAppConfigFile : 

Skipping target ,r _CopyAppConfigFile'' because all output -files are up-to-date with respect to the input files. 

Copy FilesToOutputDi rectory : 

Copying file from "obJ\Debug\ClainsProcessingBrokerAssembly.dll" to ir bin\Debug\ClaimsProcessingBrokerAssembly . dll' r . 
ClaimsProcessingBroker Project -> C : \MessageBrokerClaimsProcessorWcf5ervice\BrokerCaHWcFNodeSolution\BrokerCallWcFNodeProjec 
Copying file from ,r obj\Debug\ClaimsProcessingBrokerAssembly . pdb" to ,E bin\Debug\ClaimsProcessingBrokerAssembly . pdb". 


Build succeeded. 

Time Elapsed 00:00:05.98 

========== Build: 1 succeeded or up-to-date^ 0 failed^ 0 skipped 


< 
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Figure 7-35 Successful build output 
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7.6 Routing the output 


Now we return to the Message Broker Toolkit to continue working on the message flow. 

After the request to the WCF service is made, the output must be routed to execute 
conditional processing for some operations, and the response message must be returned to 
the client on the same transport that it was received on. For example, if the message was 
received from the SOAP input node, the reply must be made on the SOAPReply node. 
Similarly, if the message was received from the MQ Input node, the reply must be sent to the 
reply queue in the MQ Output node. 

The Flow Order node is used to route the message through the branch of the flow that checks 
if any additional processing is required. The First terminal is wired to the Flow Orderl node, 
which is the root of this branch. The branch connected to the Second terminal handles 
sending the reply message, as seen in Figure 7-36. 



7.6.1 Additional processing 

Recall from the scenario overview that there are two operations that require additional 

processing by the flow: 

ApproveClaim A payment message is generated and sent to an MQ enterprise 
application for processing. 

Create Policy A policy confirmation letter is emailed to the customer, and a file is 

sent to an external system for printing and eventually physically mailed 
to the customer as a hard copy. 

This path in the message flow is shown in Figure 7-37 on page 327. 
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The Flow Orderl node propagates the message down a branch of the flow that implements 
this additional processing. Messages that do not require additional processing are filtered out 
of execution by the Filter Nodes PaymentNeeded and PolicyDocsNeeded: 

1 . Double-click the PaymentNeeded filter node. 

2. Replace the generated code with the code in Example 7-33. 

Example 7-33 Filter Expression for PaymentNeeded Filter node 
DECLARE ns NAMESPACE 

1 http : //www. i bm. com/WebSphereMessageBroker/Exampl es/Cl aimsProcessi ng/Canoni cal Message ' ; 

CREATE FILTER MODULE IsPaymentNeeded 

CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

DECLARE paymentRef REFERENCE TO 

Root. XMLNSC. ns: Canonical Message. Appl i cat ionMessage. Cl aimsProcessi ngResponse. Approved aim 
Response. Payment; 

IF LASTMOVE (paymentRef) THEN 
RETURN TRUE; 

END IF; 

RETURN FALSE; 

END; 

END MODULE; 


This filter expression declares a reference to a path in the message that only exists for 
ApproveClaimResponse messages. In particular, the reference is declared to the Payment 
element that is required to successfully complete the processing in the 
GeneratePaymentCanonicalMessage .NETCompute node. The LASTMOVE function is 
used to test if this element exists in the Logical Message Tree. 

If the element exists, the expression returns true and execution proceeds to the 
GenereatePaymentCanonicalMessage node. If the expression returns false, ordinarily the 
message is propagated to the False terminal of the filter node. In this case, however, the 
False terminal is not wired, which means that execution on this branch of the flow 
completes. Execution will proceed from the Flow Orderl node’s Second terminal. 

Note that the namespace prefix ns is declared to the CanonicalMessage mode’s 
namespace in a global scope. This namespace declaration can then be used by 
subsequent filter nodes and compute nodes developed in this chapter. 
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3. Close the ESQL. In the Basic tab of the Properties for the PaymentNeeded node, change 
the Filter expression field to IsPaymentNeeded. 

4. The PolicyDocsNeeded Filter node performs a similar function; however, in this instance, 
rather than a Payment element, a reference is declared to the Policy element that is a child 
of the CreatePolicyResponse element, as shown in Figure 7-38. 



Figure 7-38 PolicyDocsNeeded Filter node determines if new policies need to be sent 


5. Double-click the PolicyDocsNeeded node to open the filter expression. 

6. Replace the generated code with the Filter expression in Example 7-34. 

Example 7-34 Fitter Expression for PolicyDocsNeeded Filter node 


CREATE FILTER MODULE ArePol icyDocsNeeded 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

DECLARE policyRef REFERENCE TO 

Root. XMLNSC. ns : Canoni cal Message. Appli cat ionMessage. Cl aims Process ingResponse.CreatePol icy 
Response. Pol icy; 

IF LASTMOVEf policyRef) THEN 
RETURN TRUE; 
end IF; 

RETURN FALSE; 

END; 

END MODULE; 


7. Change the Filter expression field in the properties to ArePol i cyDocsNeeded. 

If the filter expression evaluates to true, execution proceeds to the GenerateWordAttachment 
.NETCompute node. Otherwise, because the False terminal is not wired, execution completes 
on this branch of the flow and resumes on the Second terminal of the Flow Order node. 


7.6.2 Routing the reply message 

The Second terminal of the Flow Order node is attached to a branch of the flow that handles 
the reply message. To ensure that the reply is made on the correct transport, the MQorSOAP 
Filter node is used to route the message to a branch that handles the transport specific 
output. The reply message branch flow is illustrated in Figure 7-39 on page 329. 
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The filter expression for the MQorSOAP node is shown in Example 7-35. To route the reply 
message: 

1 . Double-click the MQorSOAP node to open the filter expression. 

2. Replace the generated code with the code in Example 7-35. 

Example 7-35 The filter expression for the MQorSOAP Filter node 

CREATE FILTER MODULE MQorSOAP 

CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

DECLARE soapEnvRef REFERENCE TO Local Envi ronment. SOAP. Envel ope; 

IF LASTMOVE (soapEnvRef) THEN 
RETURN FALSE; 

END IF; 

RETURN TRUE; 

END; 

END MODULE; 


3. Close the ESQL code. 

4. Update the Filter expression in the properties to MQorSOAP. 

Recall that when transforming the input message, the SOAPExtract node is configured to 
place the SOAP Envelope in the LocalEnvironment under the SOAP/Envelope path, as 
shown in Figure 7-40. 



Figure 7-40 The Envelope Destination property of the SOAPExtract node 
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The MQorSOAP filter expression declares a reference to the expected location of the 
SOAPEnvelope and uses the LASTMOVE function to determine if the element exists. If the 
SOAP Envelope exists in the LocalEnvironment tree, the expression returns False routing 
execution to the CanonicaIXMLToSOAP node. Otherwise the input message is assumed to be 
an MQ message and execution is routed to the CanonicaIXMLNSCToDFDL node. 


7.7 Writing a .NETCompute node class to generate a payment 
message 


When a Claim is approved, in addition to setting the state to Approved in the WCF service 
and sending a reply to the customer, the flow generates a message to send to a hypothetical 
payment processing system. This message causes a payment to be generated by the 
appropriate partner company that is underwriting the policy. In our example scenario, the 
application that processes the payments is a WebSphere MQ-based application that is part of 
the ESB. 

Because the receiving application is part of the ESB, there is already a Canonical Message 
defined for sending payment defined in the ClaimsProcessingCanonicalMessageModel 
library. 

Figure 7-41 shows the existing PaymentRequestType as a child of the 
ApplicationMessageType element. 


H3 PaymentRequestType 


|— [e| Payment Payment 


[FI Payment 


—[e] Amount [0 . . 1] int 

-- 

— [ej Customer [Q..1] Customer 


— [e] Underwriter [0 . . 1] string 


Figure 7-41 The PaymentRequest Type 


As shown in Figure 7-42 on page 331 , the PaymentRequestType itself is defined as a 
sequence of Payment elements. 
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E CanonicalMessageComplexType 

jgD Header 

(HeaderType) 

[Tj ApplicationMessage 

ApplicationMessageT y pe 
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H] Appld 

[o..i] 

string 


[F] Msgld 

[0..1] 

string 


= [Fj Requester 
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dateTime 

... 

[F] Command 


string 


— [Fj BusinessUnit 


string 


— [Fj BusinessUnitCode 


string 


— [Fj Reply Queue 

[Q..1] 

string 


= [F] ReplyToQm 

[0-1] 

string 


[FI ApplicationMessageType 


- [F] ClaimsProcessingRequest 
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- [1] PaymentRequest 


RequestType 


ResponseType 


Pay mentRequestT y pe 


E CTrailerType) 


P [1] Created dateTime 

I [Fj LastModified dateTime 

= [ej LastModifiedBy string 


Figure 7-42 The Canonical Message Model already defines a message for PaymentRequests 


The ApproveClaimResponse message returns a Payment element. The returned payment 
element can be used by a .NETCompute node to provide a simple transformation between 
the two message types, as shown in Figure 7-43. 



Figure 7-43 Transformation between two message types using a .NETCompute node 


To implement the .NETCompute node, open ClaimsProcessingBrokerSolution in Visual 
Studio and use the following steps: 

1 . Select Project Add Class. 

2. From the Add New Item dialog, select Message Broker Class to Modify a Message 
Broker Message. 

3. Enter GeneratePaymentNode . cs in the Name field. Click Add. 
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4. Add the code shown in Example 7-36 to the UserCode region. 

Example 7-36 GeneratePaymentNode.es 

//set these flags so that the error handler can tell where 
//any tree navigations failed 
bool canonicalMessageMatched = false; 
bool foundPaymentElement = false; 
try 
{ 

NBElement canonicalMessagelnputElement = 

inputRoot[ l, XMLNSC M ] [Constants . cp, "CanonicalMessage"] ; 
canonicalMessageMatched = true; 

NBElement appl i cationMessagelnputEl ement = canonicalMessagelnputElement 

["Appl icationMessage"] ; 

NBElement paymentlnputEl ement = applicationMessagelnputElement 

["ClaimsProcessingResponse"] ["Approved aimResponse"] ["Payment"] ; 
foundPaymentElement = true; 

NBElement appl icationMessageOutputEl ement = outputRoot ["XMLNSC"] 

[Constants. cp, "CanonicalMessage"] ["Appl icationMessage"] ; 
appl i cati onMessageOutputEl ement . Del eteAl 1 Chi 1 dren () ; 

NBElement paymentRequestOutputEl ement = appl icationMessageOutputEl ement 

.CreateFi rstChi 1 d("PaymentRequest") ; 
paymentRequestOutputEl ement .AddLastChi 1 d (paymentlnputEl ement) ; 

//Set the trailer information 

outputRoot ["XMLNSC"] [Constants .cp, "CanonicalMessage"] ["Trailer"] 

["LastModi fied"] .SetVal ue(DateTime.Now) ; 
outputRoot ["XMLNSC"] [Constants .cp, "CanonicalMessage"] ["Trailer"] 

[" LastModi fiedBy"] .SetVal ue("WebSphere Message Broker " + 
NBBroker. Broker. BrokerVersi on + " - " + 
NBBroker. Broker. Name + "." + 
NBMessageFlow.MessageFlow.Name) ; 

} 

catch (Nul 1 ReferenceExcepti on) 

{ 

//Check if the NRE is because the input tree was invalid 
if (IcanonicalMessageMatched) 

{ 

throw new NBRecoverabl eExcepti on ("Input not recognized by canonical" + 

"message model. Root tag may be incorrect." + 
"Correct input and retry."); 

} 

else if (! foundPaymentElement) 

{ 

throw new NBRecoverableException("Input recognized but could not" + 

"locate payment information. Correct input and retry."); 

} 

el se 

{ 

throw; 

} 

} 
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5. Press Ctrl+S to save GeneratePaymentNode.es. 

6. The last step is to update the GenericPaymentCanonicalMessage .NETCompute node in 
the message flow to point to the .NET assembly file and class, which we will do later in 
7.13.1 , “Building a solution” on page 358. 

Recall that when using the array syntax to reference the message tree, any failed navigation 
can result in a NullReferenceException. For this reason, boolean flags are set at the 
beginning of the method before navigating to the required portions of the input tree. 

Any NullReferenceExceptions are caught and the flags tested to determine if the exception 
occurred during navigation on the input tree. If this is the case, a new NBRecoverable 
exception is thrown to give a more meaningful message to users of the flow. 

The main code first copies the input message tree to the output tree using the code 
generated in Example 7-37. 

Example 7-37 Copying the input tree in GeneratePaymentNode.es 
NBElement inputRoot = inputMessage.RootElement; 


After copying the message tree, the ApplicationMessage element is cleared using a call to 
DeleteAIIChildren() and a new child created named PaymentRequest and then the Payment 
element from the input message is added as a child to this new Payment message. 

Finally, the trailer fields are updated to indicate that the message was modified by this node. 
The NBBroker class is used to extract runtime information, such as the name of the broker 
and the name of the message flow. 


7.8 Processing incomplete results for the 
ViewOutstandingClaims operation 

When the ViewOutstandingClaims operation encounters an error, it throws a custom Fault so 
that the consuming client can determine if it can continue with an incomplete set of results. 
This scenario is shown in Figure 7-44. 



Figure 7-44 Consuming Client is determining if it can continue with incomplete results 
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When an incoming ViewOutstandingClaims request is mapped from the DFDL domain to the 
XMLNSC domain, a variable is placed in the LocalEnvironment under the 
Variables/VIEWOUTSTANDINGCLAIMSREQUEST/ACCEPTINCOMPLETE element, as 
shown in Figure 7-45. 


□ fpj VIEWOlfTST ANDINGCL AIMSREQUEST 
!$|o <Click to filter... > 


<Anonymous> 


E ACCEPTINCOMPLETE 


[1..1] boolean 


“^|M 


(S lafel LocalEnvironment 
Jp <Click to filter... > 

_LocalEnvironmentT ype 

(S E Destination 

[0 . . 1] _LocalEnvironmentDestinatjonT ype 

IS E WrittenDestination 

[0 . . 1] _LocalEn vironmentWrittenDestinationT ype 

(S E Aggregation 

[0. . 1] _LocalEnvironmentAggregationType 

is E http 

[0 . . 1] _LocalEnvironmentHTTPT ype 

IS E File 

[0 . . 1] _LocalEnvironmentFileT ype 

IS E SOAP 

[0 . . 1] _LocalEnvironmentSO APT ype 

IS E SCA 

[0 . . 1] _LocalEnvironmentSCAT ype 

IS E Sequence 

[0 . . 1] _LocalEnvironmentSequenceT ype 

IS E TCPIP 

[0. . 1] _LocalEnvironmentTCPIPType 

IS E ServiceRegistry 

[0 . . 1] _LocalEnvironmentServiceRegistr yT ype 

IS E Adapter 

[0 . . 1] _LocalEnvironmentAdapterT ype 

IS E Wildcard 

[0 . . 1] _LocalEn vironmentWildcardT ype 

IS E Variables 

[0 . . 1] _LocalEnvironmentVariablesT ype 

<R an y 

[o..*! 

IS fjg VIEWOUTST ANDINGCLAIMSREQUEST 

[0..*] <Anonymous> 

E ACCEPTINCOMPLETE 

[L.1] boolean 

IS E cics 

[0 . . 1] _LocalEnvironmentCICST ype 


Figure 7-45 Mapping to the LocalEnvironment with the Graphical Mapper 


Placing this value in the LocalEnvironment tree allows the flow to determine if the client 
indicated that it will accept incomplete results, and this value is tested for in the error handler. 

Recall from 7.5, “Creating a .NETCompute node to consume the 

ClaimsProcessingWcfService” on page 298 that the service throws a custom fault of type 
ViewOutstandingClaimsIncompleteResultsFault. This exception type is handled separately in 
the CallWCFService .NETCompute node, as shown in Example 7-38. 

Example 7-38 Catch block for FaultException<ViewOutstandingClaimslncompleteResultsFault> in 
CallWCFNode.es 

catch (Faul t Except ion<Vi ewOut standi ngCl aimslncompl eteResul tsFaul t> e) 

{ 

//Some clients are happy with incomplete 
//results so copy the results to the environment tree 
//before rethrowing 
NBElement errorsEl ement = 

i nputAssembly . Envi ronment . Root El ement .CreateLastChi 1 d(" Errors") ; 
NBElement cl aimsEl ement = errorsElement.CreateLastChild("OutstandingClaims") ; 
foreach (Claim claim in e. Detail .OutstandingResults) 

{ 

AddCl aimEl ementToParent (cl aim, cl aimsEl ement) ; 

} 

NBElement errorDetai 1 sEl ement = errorsElement.CreateLastChild("ErrorList") ; 
foreach (ClaimProcessingFaul t fault in e. Detail .FaultList) 

{ 

errorDetai 1 sEl ement. CreateLastChi 1 d("Faul t") 

.SetVal ue(faul t . ErrorCode + 11 + faul t. Message) ; 

} 

throw; 
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The handler catches FaultExceptions with a detail type of ViewincompleteResultsFault and 
uses the OutstandingResults and FaultList collections defined on this custom type to place a 
copy of all the successfully retrieved Claim elements in the Environment tree under the 
Errors/OutstandingClaims path. Similarly, the faults that were experienced by the service are 
placed in the Environment tree under Errors/ErrorList path. 

After the details are added to the Environment tree, the exception is thrown again so that it 
can be handled upstream in the flow. Examining the flow structure, you can see that the 
CallWCFService node is preceded by a TryCatch node. This means that the ExceptionList is 
propagated down the Catch terminal to the IncompleteResults filter node, as shown in 
Figure 7-44 on page 333. 

The expression for the IncompleteResults filter node evaluates to true if the input requested 
specified that incomplete results can be accepted. It does this by checking for the presence of 
the variable, placed in the LocalEnvironment by the DFDL mapping discussed at the 
beginning of this section, and the presence of the Environment/Errors/OutstandingClaims 
element that was placed in the in the Environment tree by the CallWCFService node. The 
filter expression is shown in Example 7-39. 

1 . Double-click the IncompleteResults node. 

2. Replace the generated code for the filter with the code shown in Example 7-39. 

Example 7-39 Filter expression for the IncompleteResults node 

DECLARE nsl NAMESPACE 

1 http://www.ibm.com/WebSphereMessageBroker/Examples/Cl aimsProcessi ng/DFDLSchema ' ; 

CREATE FILTER MODULE IncompleteResults 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

DECLARE errorsRef REFERENCE TO Environment. Errors. OutstandingClaims; 

DECLARE acceptlncompl eteRef REFERENCE TO 
Local Environment. Variables. nsl: VIEWOUTSTANDINGCLAIMSREQUEST.ACCEPTINCOMPLETE; 

IF LASTMOVE (errorsRef) AND LASTMOVE(acceptlncompleteRef) AND 
FI ELDVALUE (acceptlncompl eteRef) = TRUE THEN 
RETURN TRUE; 

END IF; 

RETURN FALSE; 

END; 

END MODULE; 


3. Save and close the ESQL file. 

4. Update the properties of the node so the Filter expression field contains 
IncompleteResults. 

In this example, the existence of a tree element is tested by declaring a reference to the 
desired path and then using the LASTMOVE function to test if the parser can navigate to the 
path referred to by the reference successfully. Note that the ACCEPTINCOMPLETE variable 
was placed in the tree using the DFDL schema’s namespace during the mapping, so the nsl 
prefix is defined to match the namespace in a global declaration. 

If the filter expression evaluates to False or Unknown, the message is routed to the exception 
handler just as though the exception were caught by the input node. Otherwise, execution 
proceeds to the BuildlncompleteResultResponse .NETCompute node. The purpose of this 
node is to convert the outstanding claims list from the Environment tree into a 
ViewOutstandingClaimsResponse element in the Canonical Message XMLNSC model. 
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To create the .NET code for this node, switch to the ClaimsProcessingBrokerProject in Visual 
Studio, and follow these steps: 

1 . Select Project Add Class. 

a. From the Add New Item dialog, select Message Broker Class to Modify a 
Message Broker Message. 

b. Enter BuildIncompleteResultsResponseNode.es in the Name field. 

c. Click Add. 

2. Add the code shown in Example 7-40 to the UserCode region. 

Example 7-40 BuildlncompleteResultsResponseNode. cs 

Boolean foundErrors = false; 

Boolean foundCanonincal InputMessage = false; 
try 
{ 

NBElement outstandingClaimsElement = 

inputAssembly.Envi ronment . RootEl ement ["Errors"] [ 11 Out standi ngCl aims"] ; 
foundErrors = true; 

NBElement canoni calMessageOutputEl ement = outputRoot ["XMLNSC"] 

[Constants. cp, "CanonicalMessage"] ; 

NBElement applicationOutputEl ement = 

canoni cal MessageOutputEl ement [ 11 Appl i cati onMessage"] ; 
foundCanonincal InputMessage = true; 

appl i cati onOutputEl ement .Del eteAl 1 Chi 1 dren() ; 

NBElement vi ewOutstandi ngCl aimsResponse = appl i cati onOutputEl ement 

.CreateLastChi 1 d ("Cl aimsProcessi ngResponse") 
.CreateLastChi 1 d ("Vi ewOutstandi ngCl aimsResponse") ; 
vi ewOutstandi ngCl aimsResponse . AddLastChi 1 d (out standi ngCl aims El ement) ; 

//Set the trailer information 

outputRoot ["XMLNSC"] [Constants .cp, "CanonicalMessage"] ["Trailer"] 

["LastModi fied"] .SetVal ue(DateTime.Now) ; 
outputRoot ["XMLNSC"] [Constants .cp, "CanonicalMessage"] ["Trailer"] 

[" LastModi fiedBy"] .SetVal ue("WebSphere Message Broker " + 
NBBroker. Broker. BrokerVersi on + " - " + 

NBBroker. Broker. Name + "." + 

NBMessageFlow.MessageFl ow.Name) ; 

} 

catch (Nul 1 ReferenceExcepti on) 

{ 

if (! foundErrors) 

{ 

throw new NBRecoverabl eExcepti on ("No incomplete results were found" + 

"to process") ; 

} 

else if (! foundCanonincal InputMessage) 

{ 

throw new NBRecoverabl eExcepti on ("Input not recognized by canonical" + 

"message model. Root tag may be incorrect." + 
"Correct input and retry."); 

} 

throw; 
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} 


3. Press Ctrl+S to save BuildlncompleteResultsResponse.es. 

Failed tree navigations can result in NullReferenceExceptions being thrown from expressions, 
such as inputAssembly.Environment.RootElement["Errors"]["OutstandingClaims"]. If, for 
example, the EnvironmentRoot/Errors element did not exist, that is the equivalent of calling 
null[“OutstandingClaims”], which results in an exception. For this reason, 
NullReferenceExceptions are caught and some boolean flags tested to see if the NRE was 
the result of a failed tree navigation. If this is the case, an NBRecoverable exception is thrown 
instead with a more meaningful error message; otherwise, the NRE is thrown again with the 
throw; statement. 


Correct syntax for throwing exceptions: Unlike in Java, it is not correct to throw the 
exception by name, for example, using syntax, such as catch (Exception e) { throw e; }. 
Using this syntax results in the stack trace for the exception being overridden and the throw 
statement in the catch block being the new origin point of the exception stack. This is 
because throw e; gets compiled into the MSIL throw instruction. Instead use the syntax 
catch (Exception) { throw; }, which compiles into the MSIL re-throw instruction that 
gives the desired behavior. 


The main code path of the node deletes all children of the 
CanonicalMessage/ApplicationMessage element and creates a new child named 
ClaimsProcessingResponse. A new child of this ClaimsProcessingResponse element is 
created called ViewOutstandingRequests, and then the OutstandingClaims element from the 
Environment tree is added as a child to the ViewOutstandingRequests element. This 
structure was created by the CallWCFService node in the catch block for 
FaultException<ViewOutstandingClaimslncompleteResults> exceptions, as shown in 
Example 7-38 on page 334. 

Finally, the trailer is updated to indicate that the message flow modified the message. The 
NBBroker class is again used to access runtime information about the broker and the 
message flow. 

If execution of the compute node completes successfully, the message is propagated back 
into the main line of the flow to the Flow Order node exactly as though the 
CallWCFCIaimsService had completed successfully. 


7.9 Creating a Word document for email and print 

When the CreatePolicy operation is invoked, the flow needs to generate a Word document to 
send to the customer that contains the details of their newly purchased policy. This can be 
done using a .NETCompute node, as shown in Figure 7-46 on page 338. 

The C# code in this chapter takes data from the broker logical tree and uses it to create a 
Microsoft Word document. The code uses the Open XML Format SDK (Version 2), which is 
an API for the .NET Framework that enables developers in both client and server 
environments to interact with Microsoft Word. 
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Figure 7-46 A customer document detailing policies is created in the .NET node 


7.9.1 Preparing a letter template 

Before implementing the .NETCompute node, prepare a template for the policy confirmation 
letter. 

To create the template: 

1 . Open a new Word document with Microsoft Word 2010. 

2. In the document, put your cursor where you want to add the content control, or select the 
text that you want the content control to replace. 

3. Click the Developer tab. 

If the Developer tab is not visible, you must first show the Developer tab for Microsoft 
Office 2010 applications: 

a. Click the File tab. 

b. Click Options. 

c. In the categories pane, click Customize Ribbon. 

d. In the list of main tabs, select Developer. 

e. Click OK to close the Options dialog box. 

4. Click Design Mode in the Controls section, as shown in Figure 7-47. 


Aa Aa 0 Design Mode 

iff! J H iS 1 Properties 
If IS’ K Group 
Controls 

Figure 7-47 Switch to design mode 

5. In the Controls section, click Plain Text Content Control, as shown in Figure 7-48 on 
page 339. 
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Plain Text Content Control 

Insert a plain text content control. 


Figure 7-48 Plain Text Content Control selection 


6. In the new content control field, type Reci pi ent, as shown in Figure 7-49. 



Figure 7-49 New content control field 

7. Right-click the content control and select Properties, as shown in Figure 7-50. 
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Figure 7-50 Select properties when preparing a letter template 


8. Enter Name as the tag, as shown in Figure 7-51 on page 340. Click OK. 

Later, in “Creating a helper method” on page 345, you will code a .NET application to 
populate this template using these tags to identify the fields. 
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Figure 7-51 Properties for the content control field 

9. Continue building the template using Figure 7-52 as a guide. The form is a mix of text and 
content control fields. 


ITSO Insurance 

Policy Number: 

Department Building 123 

policy number 4025-62 policy number 

123 Main St. 

Coverage Period: 

Any City, Any State USA 

poFicystart 12-26-11 policy start 

through 

name Recipient name 

policy expire 06-26-12 policyeipire 

(^address ( AddreSS ) address ^ 

12:01 a.m. local time at the address of the named 
insured. 

A** March 19, 2012 3Ire 


dear Dear dear 



Figure 7-52 Content control example 


10. Save and close the template. 

7.9.2 Creating a user-defined property for the template location 

To create a user-defined property for the node: 

1 . Click the User Defined Properties tab on the bottom of the message flow editor. 

2. Right-click ClaimProcessFlow Basic -» Add Property: 

a. Rename the property Tempi ateLocati on. 

b. In the Default value field, enter the location of the template. 

Figure 7-53 on page 341 shows the new property settings. 
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User Defined Properties 

User Property Hierarchy 

Details 

View and edit the item selected in the property hierarchy. 


m c x 

□ ■ Hi ClaimProcessFlow 
-] l!_u| Basic 

i ] FromEmail 

TemplateLocation 

Type String 


Default Value | c:\temp\testData\templates\PolicyConfirmation.docxl 

l~l Mandatory 


Figure 7-53 TemplateLocation user defined property 


3. Press Ctrl+S to save your changes. 

4. Switch back to the Graph view. 

7.9.3 Creating .NET code to generate a Word document using a template 

This process creates the .NET code for the GenerateWordAttachment .NETCompute node. 
With the ClaimsProcessingNodeProject open in Visual Studio, follow these steps: 

1 . Select Project Add Class. 

2. From the Add New Item dialog, select Message Broker Class to Modify a Message 
Broker Message. 

3. Enter BuildEmailAttachmentNode.es in the Name field, and click Add. 

Adding references to the project 

Because you create and update the Word document with the Open XML SDK 2.0 API, you 
need to add it into reference. To add the Word document into reference: 

1 . In the hierarchy in Solution Explorer, right-click References -» Add Reference. 

2. In the Add Reference dialog, switch to the .NET tab, and select 

DocumentFormat.OpenXml. 

If you cannot find the entry, first make sure that you sorted the components alphabetically. 
If the entry is definitely not in the list, follow the previous instructions to download and 
install the Open XML SDK 2.0 API. 

3. Click OK. 

4. Using the same process, add a reference to the WindowsBase reference. 

Overriding the Evaluate method 

The Evaluate() method builds a Microsoft Word document that contains the new policy 
document that is sent to the customer: 

1 . Replace the code for the Evaluate() method in BuildEmailAttachmentNode.es with the 
code in Example 7-41 . 

Example 7-41 Add the Evaluate method to the project 

public override void Evaluate(NBMessageAssembly i nputAssembly) 

{ 

NBOutputTerminal outTerminal = OutputTerminal ("Out") ; 

NBMessage inputMessage = inputAssembly .Message; 

// Create a new empty message, ensuring it is disposed after use 
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using (NBMessage outputMessage = new NBMessageQ) 

{ 


NBElement inputRoot = i nputMessage. RootEl ement ; 

NBElement outputRoot = outputMessage. RootEl ement ; 

// Optionally copy message headers, remove if not needed 
CopyMessageHeaders (i nputRoot, outputRoot) ; 

#region UserCode 

// Add user code in this region to modify the message 
// create attachment properties folders in the local environment 
NBMessage local Environment = inputAssembly. Local Environment; 

NBMessage newEnvi ronment = new NBMessage(i nputAssembly . Local Environment) ; 

// add environment tree to output message assembly 
NBMessageAssembly outAssembly = new NBMessageAssembly(inputAssembly, outputMessage, 
newEnvi ronment) ; 

// check response type 

NBElement canonicalMessageElement = inputRoot["XMLNSC"] [Constants. cp, "CanonicalMessage"] ; 
NBElement cl aimsProcessi ngResponseEl ement = 
canoni cal MessageEl ement [ 11 Appl i cati onMessage"] [ M C1 aimsProcessi ngResponse"] ; 

NBElement pol i cyEl ement = 

cl aimsProcessi ngResponseEl ement [ 11 CreatePol i cyResponse"] ["Pol i cy M ] ; 

NBElement emai 1 OutputHeader = outputRoot. CreateLastChild("EmailOutputHeader") ; 

// read template into memory stream 

byte[] byteArray = Fi 1 e.ReadAl 1 Bytes (GetUserDefi nedPropertyAsStri ng( "Tempi ateLocation") ) ; 
using (MemoryStream mem = new MemoryStreamO) 

{ 

mem.Wri te (byteArray, 0, (i nt) byteArray. Length) ; 

CreatePol i cyWordDocumentMemoryStream(pol icyEl ement, mem) ; 

//add mem stream to output bitstream 

Byte [] myBytes = new Byte[(i nt)mem. Length] ; 
myBytes = mem.ToArray () ; 

outputRoot .CreateLastChi 1 dlls i ngNewParser(NBParsers .BLOB. ParserName) ; 

NBElement blob = outputRoot [NBParsers. BLOB. ParserName] .CreateLastChi 1 d("BL0B") ; 
string samplemsg = "This is the confirmation letter of your policy"; 

Byte [] emailbody = System. Text. Encoding. ASCII. GetBytes (samplemsg) ; 
bl ob.SetVal ue(emai 1 body) ; 

// create an email properties folders 

emai 1 OutputHeader. CreateLastChi 1 d("To") .SetVal ue(pol i cyEl ement ["Pol i cyHol der"] ["Emai 1 "] . Val ueAsS 
tring) ; 

emai 1 OutputHeader. CreateLastChi 1 d("From") .SetVal ue (GetUserDefi nedPropertyAsStri ng("FromEmai 1 ") ) ; 

emai 1 OutputHeader. CreateLastChi 1 d(" Subject") .SetVal ue("Pol i cy Confi rmation 
from ITSO Insurance"); 

//setting unique file name 

string filename = "Pol icyConfi rmation" + DateTime. Today. ToLongDateStringQ + ".docx"; 
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//Set attachment details into the local env tree 

NBElement destination = newEnvironment.RootElement.CreateLastChild("Destination") ; 
NBElement attachmentEl ement = 

desti nati on.CreateLastChi 1 d("Emai 1 11 ) .CreateLastChi 1 d ("Attachment") ; 

attachmentEl ement .CreateLastChi 1 d("ContentName") .SetVal ue(fi 1 ename) ; 
attachmentEl ement .CreateLastChi 1 d(" Content Encodi ng") .SetVal ue( l, Base64") ; 
attachmentEl ement .CreateLastChi 1 d("Content") .SetVal ue(myBytes) ; 

//propagate 

outTermi nal . Propagate(outAssembly) ; 

} 

#endregion UserCode 

} 


2. Add the following Using statements for the Open XML API classes so that we can code 
without using a fully-qualified name. See Example 7-42. 

Example 7-42 Using directives 

using DocumentFormat .OpenXml ; 

using DocumentFormat .OpenXml .Packaging; 

using DocumentFormat .OpenXml .Wordprocessing; 


3. Instead of opening a file from the disk or a file share, we work with a document in memory. 
Retrieve a document from the document library as a byte array, and then modify it as 
necessary. Put it back into the document library as a new document. When engaged, as 
shown in Example 7-43, this aspect opens to use System. 10. 

Add the following using statement: 

using System. 10; 

The Template class does not access the LocalEnvironment Message. Looking at code for the 
Evaluate() method in Example 7-43, you can see that a new message assembly was included 
and other areas were commented out. 

Example 7-43 New message assembly 

// NBMessageAssembly outAssembly = new NBMessageAssembly (i nputAssembly, 
outputMessage) ; 

#region UserCode 

// Add user code in this region to modify the message 

NBMessage local Environment = i nputAssembly. Local Envi ronment; 

NBMessage newEnvi ronment = new NBMessage(i nputAssembly. Local Environment) ; 
NBMessageAssembly outAssembly = new NBMessageAssembly (i nputAssembly, 
outputMessage, newEnvi ronment) ; 


In Example 7-44 on page 344, we created a message element reference that points to the 
response message payload. We also created emailOutputHeader that will hold the detail 
about the email. 
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Example 7-44 Message element reference and emailOutputHeader 


NBElement canonicalMessageElement = i nputRoot ["XMLNSC"] [Constants. cp, 
"CanonicalMessage"] ; 

NBElement cl aimsProcessi ngResponseEl ement = 

canoni cal MessageEl ement [ 11 Appl i cati onMessage"] ["Cl aimsProcessi ngResponse"] ; 
NBElement pol i cyEl ement = 

cl aimsProcessi ngResponseEl ement [ 11 CreatePol i cyResponse"] ["Pol i cy M ] ; 

NBElement emailOutputHeader = outputRoot.CreateLastChild("EmailOutputHeader M ) ; 


We read the name and path to the letter template from user-defined properties, and we read it 
into In-Memory stream, as shown in Example 7-45. 

Example 7-45 Name and path of the letter template 
byte[] byteArray = 

File. ReadAl 1 Bytes (GetUserDef i nedPropertyAsStri ng ( "Tempi ateLocati on ") ) ; 

using (MemoryStream mem = new MemoryStreamQ) 

{ 

mem.Wri te (byteArray, 0, (i nt) byteArray. Length) ; 


The following example calls our own method that updates the template based on the 
information that is available in the response message. We will create this helper method later. 

CreatePol i cyWordDocumentMemoryStream(pol icyEl ement, mem) ; 

After updating the template, we copy it over to bitstream, as shown in Example 7-46. 

Example 7-46 Copy the template to bitstream 

Byte[] myBytes = new Byte[(int)mem. Length] ; 
myBytes = mem.ToArray () ; 


We then prepare the message that will be included in the email body, and put it in the 
message tree, as shown in Example 7-47. 

Example 7-47 Create the body of the message 

output Root .CreateLastChi 1 dllsi ngNewParser(NBParsers. BLOB. ParserName) ; 

NBElement blob = outputRoot[NBParsers. BLOB. ParserName] .CreateLastChi 1 d("BL0B") ; 
string samplemsg = "This is the confirmation letter of your policy"; 

Byte[] emailbody = System. Text. Encoding. ASCII. GetBytes (samplemsg) ; 

blob.SetVal ue(emai 1 body) ; 


In the last section of code for the Evaluate method, we define the details about the email 
header and attachment and then propagate the results to the output terminal (Example 7-48). 

Example 7-48 Define details for the message header and attachment 

emai lOutputHeader. CreateLastChi 1 d("To") .SetVal ue(pol i cyEl ement ["Pol i cyHol der"] ["Em 
ail "] .ValueAsString) ; 

emai lOutputHeader. CreateLastChi 1 d("From") .SetVal ue (GetUserDef i nedPropertyAsStri ng( 
"FromEmai 1 ") ) ; 
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emai lOutputHeader.CreateLastChi 1 d( 11 Subject") .SetVal ue("Pol i cyConfi rmati on from 
ITSO Insurance"); 

string filename = 11 Pol i cyConfi rmati on 11 + DateTime. Today. ToLongDateStringO + 

11 .docx" ; 

NBElement destination = newEnvironment.RootElement.CreateLastChild("Destination") ; 
NBElement attachmentEl ement = 

desti nati on.CreateLastChi 1 d( 11 Emai 1 11 ) .CreateLastChi 1 d ("Attachment") ; 

attachmentEl ement .CreateLastChi 1 d("ContentName") .SetVal ue(fi 1 ename) ; 
attachmentEl ement .CreateLastChi 1 d("ContentEncodi ng") .SetVal ue("Base64") ; 
attachmentEl ement .CreateLastChi 1 d("Content") .SetVal ue(myBytes) ; 

outTerminal . Propagate (outAssembly) ; 

} 

#endregion UserCode 


Creating a helper method 

To create a helper method: 

1 . Add the code shown in Example 7-49 after the Evaluate method, in 
BuildEmailAttachmentNode.es. 

Example 7-49 Create a helper method 

private static void CreatePol i cyWordDocumentMemoryStream(NBEl ement pol i cyEl ement, MemoryStream 
mem) 

{ 

using (Wordprocessi ngDocument wordDoc = WordprocessingDocument.Open(mem, true)) 

{ 

Mai nDocumentPart DocPart = wordDoc. MainDocumentPart; 

Li st<SdtBlock> sdtList = DocPart. Document. Descendants<SdtBlock>() .ToList() ; 
foreach (SdtBlock sdt in sdtList) 

{ 

string aliasname = sdt.SdtProperties.GetFirstChild<Tag>() . Val ; 

SdtContentBl ock contentblock = sdt.Descendants<SdtContentBlock>() . Fi rstOrDefaul t () ; 

Text text = contentblock. Descendants<Text>() .FirstOrDefault() ; 

//update content block 
switch (aliasname) 

{ 

case "name": 

//add customer name on header 

text. Text = pol i cy El ement ["Pol icyHolder"] ["Surname"] . Val ueAsStri ng 
+ ", " + pol i cyEl ement ["Pol i cyHol der"] ["Fi rstName"] .Val ueAsStri ng; 
break; 

case "address": 

// add address 

text. Text = pol icy El ement ["Pol icyHolder"] ["Address"] .Val ueAsStri ng; 
break; 

case "pol i cynumber" : 

// add policy number 

text. Text = policyElement["PolicyNumber"] .Val ueAsStri ng; 
break; 

case "policystart" : 
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// add policy starting date 

text. Text = pol i cyEl ement ["Pol i cyStartDate"] .GetDateTime() .ToLongDateStri ng() ; 
break; 

case "pol i cyexpi re" : 

// add policy expiring date 

text. Text = pol i cyEl ement ["Pol i cyExpi ryDate"] .GetDateTime() .ToLongDateStri ng() ; 
break; 

case "date": 

// add today's date 

text. Text = DateTime. Today. ToLongDateStri ng() ; 
break; 

case "dear": 

// add customer name in body 

text. Text = "Dear " + policyElement["PolicyHolder"] ["Surname"] .ValueAsString 
+ ", " + policyElement["PolicyHolder"] ["FirstName"] .ValueAsString; 
break; 

} 

} 

//complete the update 
wordDoc.Close() ; 

} 


2. Save the code. 

Looking at the code, you can see that it opens the letter template stored in In-Memory stream 
using Open XML API (Example 7-50). 

Example 7-50 Open the letter template 

using (WordprocessingDocument wordDoc = WordprocessingDocument.Open(mem, true)) 

{ 

Mai nDocumentPart DocPart = wordDoc. Mai nDocumentPart; 


Next, it locates all content controls in the template (Example 7-51). 

Example 7-5 1 All content controls 

Li st<SdtBl ock> sdtList = DocPart. Document. Descendants<SdtBlock>() .ToListQ ; 


It then loops through the list of content controls and updates the template based on the 
information about the response message (Example 7-52). 

Example 7-52 Update the template 

foreach (SdtBlock sdt in sdtList) 

{ 

string aliasname = sdt.SdtProperties.GetFirstChild<Tag>() . Val ; 

SdtContentBlock contentblock = 

sdt.Descendants<SdtContentBl ock>() . Fi rstOrDefaul t () ; 

Text text = contentbl ock.Descendants<Text>() . Fi rstOrDefaul t() ; 

switch (al iasname) 

{ 

case "name": 

text. Text = pol i cyEl emen t ["Pol icyHolder"] ["Surname"] .ValueAsString 
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+ ", 11 + pol i cy El emen t [ 11 Pol i cyHol der M ] ["FirstName"] . Val ueAsStri ng; 
break; 

case "address": 

text. Text = pol i cyEl emen t ["Pol icyHolder"] ["Address"] .Val ueAsStri ng; 
break; 

case "pol icynumber" : 

text. Text = policyElement["PolicyNumber"] .Val ueAsStri ng; 
break; 

case "pol icystart" : 
text. Text = 

pol i cyEl emen t ["Pol i cyStartDate"] .GetDateTime() .ToLongDateStri ng() ; 
break; 

case "pol icyexpire" : 
text. Text = 

pol i cyEl emen t ["Pol i cyExpi ryDate"] .GetDateTime() .ToLongDateStri ng() ; 
break; 

case "date": 

text. Text = DateTime. Today. ToLongDateStri ng() ; 
break; 

case "dear": 

text. Text = "Dear " + 

pol i cyEl ement [" Pol i cyHol der"] ["Surname"] . Val ueAsStri ng 

+ ", " + policyElement["PolicyHolder"] ["FirstName"] .ValueAsString; 

break; 

} 

} 


The code then saves the update and completes the method definition (Example 7-53). 

Example 7-53 Update the method definition 
wordDoc.Close() ; 


7.9.4 Using the EmailOutput node to send an email to the customer 

When a new policy is created, the message is routed to the BuildEmailAttachment node. It 
creates a Microsoft Word document using the template that contains the confirmation and 
sends it to the customer as an email attachment, as shown in Figure 7-55 on page 348. 


Chapter 7. Scenario: Integrating Windows Communication Foundation in message flows - Part 2 347 







Figure 7-54 Flow order showing the point at that an email is sent to the customer 


The GenerateWordAttachment .NETCompute node produces a bitstream that contains the 
customized word document and places it in the LocalEnvironment tree under the 
Destination/Email/Attachment/Content path. The EmailToCustomer email node automatically 
converts this content into an attachment when it sends the output message. 


7.9.5 Using the FileOutput node to send the file for printing 

After the new policy confirmation document is emailed to the customer, it also needs to be 
sent to a printer so that a hard copy can be mailed to the customer’s address. The printing 
service requires the file to be placed in the file system using the FileOutput node, illustrated in 
Figure 7-55. 



The attachment is currently located in the message tree in the LocalEnvironment so that the 
EmailOutput node can construct an email message. The FileOutput node requires the 
document to be in the message body, so we need to perform some simple transformation in 
an ESQL Compute node to move the element from the LocalEnvironment tree to the Body. 

1 . Double-click the MoveAttachmentToBody compute node to open the ESQL. 

2. Change the name of the module to MoveAttachmentToBody. 
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3. Replace the BEGIN/END block in the Main() function with the content in Example 7-54 on 
page 349. 

Example 7-54 Transform the ESQL Compute node 
BEGIN 

CALL CopyMessageHeaders() ; 

SET OutputRoot. BLOB. BLOB = 

Input Local Envi ronment .Desti nation. Emai 1 .Attachment. Content ; 

RETURN TRUE; 

END; 


4. Close the ESQL 

5. In the Basic tab of the Properties view for the node, change the ESQL module to 
MoveAttachmentToBody. 

This code moves the bitstream attached on the LocalEnvironment tree to the message body 
so that FileOutputNode can generate the same documentation attached on the email. The 
attachment itself is binary data, so we used the BLOB parser to ensure that no conversion 
happens on serialization by the FileOutput node. FileOutput node’s Data location property is 
configured to extract the data from Message Body, as described in “SendForPrinting node” on 
page 287. 


7.10 Using the Mapping node to transform the Canonical 
message to the output format 

The flow must ensure that requests that originated from an MQ client receive a reply on the 
MQ transport. Requests that arrived on the MQInput node are routed to the branch of the flow 
that converts the XMLNSC Canonical message into the binary format used by the MQ clients 
before sending the reply. The binary format is modelled in the DFDL domain so a Graphical 
Mapping node can be used to perform the transformation, as show in Figure 7-56. 

The CanonicaIXMLNSCToDFDS node was configured in “CanonicaIXMLNSCToDFDL node” 
on page 289. This section takes a closer look at this mapping function. 



Figure 7-56 Mapping a Canonical Response message into a DFDL domain message 
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An example XMLNSC response for the ViewClaim operation is shown in the WebSphere 
Message Broker flow debugger in Figure 7-57 on page 350. 
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Figure 7-57 A ViewClaimResponse in XMLNSC Canonical Message Format 


The output format for the flow is modelled by the REPLY message in the 
ClaimsProcessing.xsd model that is defined in the ClaimsProcessingDFDLMessageFormats 
library. The message is shown in the DFDL editor in Figure 7-58. 
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Figure 7-58 The DFDL definition for the reply message for the CreateClaim response 


The CanonicaIXMLNSCToDFDL node uses the Graphical Data Mapper to convert between 
the XMLNSC format and the DFDL reply format. 
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Additional material: The building of the map is beyond the scope of this chapter; however, 
you can explore the completed mapping in the CanonicalXMLNSCToDFDL.map files by 
downloading them from the additional materials and importing them to the Message Broker 
Toolkit. You can access the mapping editor by either double-clicking the map file in the 
Explorer pane or double-clicking the node itself. 


Figure 7-59 shows the top level mapping. 



Figure 7-59 The top level map in CanonicalXMLNSCToDFDL.map 


The map uses the Conditional mapping construct to run a specific submap, depending on the 
type of response that was received. In a Conditional mapping, it is possible to add individual 
conditions that are only executed when the XPath expression in the Condition property is 
satisfied by the input message. In this example, the XPath count() function is used to 
determine if there is a ViewClaimResponse element in the tree. 

Figure 7-60 on page 352 highlights an inner section of the local map that maps an XMLNSC 
Claim element onto a DFDL CLAIMLIST element using Move operations. Each Move 
operation was created by simply dragging the source field on the left onto the target field on 
the right. 
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Figure 7-60 Mapping an XMLNSC Claim element onto a DFDL CLAIMLIST element 


The mapping itself only needs to alter the logical structure of the message. Any physical 
representation, such as delimiters, terminators, and initiators, are added by the DFDL parser 
when the logical message tree is serialized by the MQOutput node. 

An extract from serialized ViewClaim message is shown in Figure 7-61. 
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Figure 7-61 A serialized ViewClaim message 
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7.1 1 Using a Compute node to transform the Canonical 
Message into a SOAP message 


The expected response for the SOAP request is a single Claim element. The transformation 
from a CanonicaIXML Message to a SOAP message, as shown in Figure 7-62, can therefore 
be done by copying the message from the input tree and placing it in the correct namespace 
of the SOAP request. 



Figure 7-62 Transforming a CanonicaIXML Message to a SOAP Message 


1 . Double-click the CanonicaIXMLToSOAP node to open the ESQL. 

2. Change the name of the new module to Canoni cal XMLToSOAP. 

3. Replace the Main() function with the code shown in Example 7-55. 

Example 7-55 The CanonicaIXMLToSOAP node. 

CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

CALL CopyMessageHeaders() ; 

CREATE LASTCHILD OF OutputRoot DOMAIN ( 'XMLNSC' ) ; 

SET OutputRoot. XMLNSC. sp: Cl aimRef Element = 

InputRoot. XMLNSC. ns: Canoni cal Message. Appl i cationMessage 

.ClaimsProcessi ngResponse. ViewCl aimResponse.Cl aim; 

RETURN TRUE; 

END; 


4. Update the properties for the node, pointing the ESQL module field to 
CanonicaIXMLToSOAP. 

We do not need to build a SOAP envelope because the SOAP Reply node does it 
automatically when it receives the message. 


7.12 Handling exceptions in the flow 

The flow needs to handle exceptions that occur and convert these into meaningful messages 
that can be handled by the client. This process is shown in Figure 7-63 on page 354. 
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In the case of the SOAP transport, we leave exceptions unhandled and allow the message 
flow to automatically return a SOAP fault to the application. 


Note: The SOAP fault thrown contains full details of the exception. In some environments, 
this is seen as a security risk. In fact, it is even possible to use the content of SOAP faults 
to decrypt intercepted messages from an HTTPS session. For this reason, WebSphere 
Message Broker provides the ability to make the faults that are returned to the client 
anonymous. This can be enabled by setting the Java property: 

IBM_JAVA_OPTIONS=-Dwebservi ces . uni fy . faul t=true 

This property is set in the Broker's profile (%MQSI_FILEPATH%\bin\mqsiprofile.cmd on 
Windows or $MQSI_FILEPATH/mqsiprofile on UNIX. 


For the MQ transport, the error handling needs to be more sophisticated so that diverse 
heritage applications can act appropriately on errors. The strategy followed when an 
exception occurs in the messageflow is to log an informational message to an error queue. 
The informational message is in human-readable XML, and the content is based on the 
exception list structure in the message assembly. Message Broker automatically places 
details that relate to the error encountered in this exception list structure. A reply message is 
then sent to the application with a non-zero completion code to indicate failure. This message 
also contains the msgld of the message put to the error queue so that the application can 
examine the failure reason if required. 

The ConvertExceptionListToMessage node is responsible for navigating through the 
ExceptionList tree and building the XML error message. 

1 . Double-click the ConvertExceptionListToMessage node to open the ESQL. 

2. Change the name of the module to ConvertExceptionListToMessage. 

3. Replace the Main() function with the code shown in Example 7-56 to the 
ConvertExceptionListToMessage node. 

Example 7-56 Building the XML exception message 

CREATE FUNCTION MainQ RETURNS BOOLEAN 
BEGIN 

CALL CopyMessageHeadersO ; 

CREATE LASTCHILD OF OutputRoot DOMAIN ( 'XMLNSC 1 ) ; 
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SET OutputRoot.XMLNSC. (XMLNSC. Xml Declaration)*. (XMLNSC.Attribute)Version = '1.0'; 
SET OutputRoot.XMLNSC. (XMLNSC. Xml Declaration)*. (XMLNSC. Attribute) Encoding = ' UTF-8 1 ; 
CREATE LASTCHILD OF OutputRoot.XMLNSC NAME( ' ERRORMESSAGE 1 ) ; 

DECLARE outputRef REFERENCE TO OutputRoot.XMLNSC. ERRORMESSAGE; 

DECLARE exceptionRef REFERENCE TO InputExceptionList.*[l] ; 

WHILE LASTMOVE (except i onRef ) DO 

IF exceptionRef. Number IS NOT NULL THEN 

CREATE LASTCHILD OF outputRef NAME( 1 ERROR' ) VALUE ( ' ERRORNUM: ' || 
CAST(exceptionRef. Number AS CHARACTER) || 1 TEXT:' || 

exceptionRef .Text) ; 

END IF; 

MOVE exceptionRef LASTCHILD; 

END WHILE; 

RETURN TRUE; 


4. Update the properties of the node so that the ESQL module field points to the 
ConvertExceptionListToMessage module. 

The node starts out by taking a copy of the message headers from the input message, which 
provides the output message tree with a suitable properties folder and MQMD. We then 
create a new XMLNSC tree with an XML declaration. 

The error message we are building has a root element of <ERRORMESSAGE> that is 
created using the CREATE LASTCHILD statement. 

We then declare two references, the first outputRef is declared to the <ERRORMESSAGE> 
element that was just created and this will be used to add new elements into the output tree. 
The second is declared to the first child of the InputExceptionList tree. The * (asterisk) 
operator will select any element regardless of name and the [1] is an index to the first 
element matching. 

ExceptionLists are nested structures with each exception containing exceptions relating the 
root cause. It is typical for an additional layer of exception wrapping to occur in each node that 
attempts to handle the exception and failed. The WHILE loop iteratively traverses the 
ExceptionList tree by moving to the last child setting, a new child of the <ERRORMESSAGE> 
root element, to a concatenation of the BIP error number and the exception text. 

An example ExceptionList is shown in the WebSphere Message Broker Flow Debugger in 
Figure 7-64 on page 356. 
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E ❖ RecoverableException 
♦ File 

F : V^uildV^800_P V-^rc V-PataFlowEngineWlmbDataFlowNode . cpp 

^ Line 

1129 

^ Function 

ImbDataFlowNode : : createExceptionList 

& Type 

ComlbmT ry CatdiNode 

& Name 

ClaimProces5ingFlow#FCMComposite_l_22 

^ Label 

ClaimProcessingFlow.Try Catch 

^ Catalog 

BIPmsgs 

^ Severity 

3 

^ Number 

2230 

& Text 

Node throwing exception 

□ ^ RecoverableException 

File 

F : \V3uild\^800_P\^rc\V)ataFlowEngine\ , V^otNet\ , V-ibrary\\ImbDotNetComputeNode . cpp 

^ Line 

417 

^ Function 

ImbDotNetComputeNode: evaluate 

& Type 

ComlbmDotNetComputeNode 

^ Name 

ClaimProcessjngFlow#FCMComposite_l_3 

^ Label 

ClaimProcessingFlow . Call WCFSer vice 

❖ Catalog 

BIPmsgs 

^ Severity 

3 

^ Number 

2230 

Text 

Caught exception and rethrowing 

© ❖ RecoverableException 
File 

^ Line 

0 

^ Function 
^ Type 
^ Name 
^ Label 

^ Catalog 

BIPmsgs 

^ Severity 

3 

^ Number 

7499 

& Text 

CLAIMSPROCESSING FAULT. Code: ERR004 ErrorText: Could not view daim. Reason: Claim CLAIM1Q1 does not exist. 

© ^ Insert 


Figure 7-64 The nested ExceptionList structure 


Output from the same exception after it is processed by the ConvertExceptionListToMessage 
node can be seen using the ERROFLQUEUE Dequeue file from the 
ClaimsProcessingMQTest Test Client. The XML structure is shown in Example 7-57. 

Example 7-57 The XML Error Message 

<?xml version="1.0" encodi ng="UTF-8"?> 

<ERRORMESSAGE> 

<ERR0R> 

ERRORNUM: 2230 TEXT:Caught exception and rethrowing 
</ERR0R> 

<ERR0R> 

ERRORNUM: 7499 TEXT:CLAIMSPROCESSING FAULT. Code: ERR004 
ErrorText: Could not view claim. Reason: Claim CLAIM101 
does not exist. 

</ERR0R> 

</ERR0RMESSAGE> 


As you can see, the exception structure was flattened from a nested parent-child relationship 
into a list for processing in connected MQ applications. 

After the error message is sent to the ERROR_QUEUE, the flow needs to build an error reply 
to send back to the reply queue. This is performed by the BuildErrorReplyMessage node. 
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1 . Double-click the BuildErrorReplyMessage node to open the ESQL. 

2. Replace the Main() function with the code shown in Example 7-58. 

Example 7-58 Building the error reply message 

CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

CALL CopyMessageHeaders () ; 

-- Create a new DFDL output message 

SET OutputRoot.MQMD.Correl Id = InputRoot .MQMD.Msgld; 

CREATE LASTCHILD OF OutputRoot DOMAIN ( 1 DFDL 1 ) ; 

SET OutputRoot. DFDL. nsl : REPLY. COMPLETIONCODE = 1; 

SET OutputRoot. DFDL. nsl : REPLY. ERRORMSGID = InputLocal Envi ronment 
.Wri ttenDesti nation.MQ.Desti nati onData.msgld; 

SET OutputRoot. DFDL. nsl : REPLY. ERRORTEXT = 

'PROCESSING FAILED. ERROR MESSAGE WRITTEN TO ERROR QUEUE WITH 1 
|| 'SPECIFIED MSGID' ; 

--Build the destination list 

SET OutputLocal Envi ronment . Desti nati on .MQ. Desti nati onData . queueName = 

InputRoot .MQMD. ReplyToQ; 

SET OutputLocal Envi ronment . Desti nati on .MQ. Desti nati onData 
.queueManagerName = InputRoot. MQMD. ReplyToQMgr; 

RETURN TRUE; 

END; 


3. Update the properties for the BuildErrorReplyMessage node so that the ESQL module 
field points to BuildErrorReplyMessage. 

The REPLY message in the DFDL domain for an error message consists of a sequence of 
COMPLETIONCODE, ERRORMSGID, and ERRORTEXT, as shown in the DFDL editor in 
Figure 7-65. 



Figure 7-65 The REPLY message shown in the DFDL editor 

The code for the BuildErrorReplyMessage first copies the headers so that we have a suitable 
Properties tree and MQMD for propagation. The Correlld is set to the input msgld so that the 
reply can be correlated with the request message by the MQ application that receives the 
reply. We then create a new message body using the DFDL parser and set the completion 
code to 1 to indicate a failure. 

When the MQOutput node writes a message to a queue it places information about the MQ 
PUT operation in the LocalEnvironment under the WrittenDestination folder. This information 
is used to set the ERRORMSGID to the msgld of the MQ message sent to the 
ERROR_QUEUE. 
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Finally, the LocalEnvironment is updated with the DestinationData associated with the reply 
details so that the subsequent MQOutput node sends the message to the correct queue and 
queue manager. 


7.13 Building and deploying the Visual Studio project 

The code for the .NETCompute nodes was created in a Visual Studio solution called 
ClaimsProcessingBrokerProject. That code needs to be assembled in order for the 
.NETCompute nodes to reference the files. 

7.13.1 Building a solution 

To build a solution: 

1 . Open the ClaimsProcessingBrokerProject solution in Visual Studio. 

1 . From the Solution Explorer, right-click the project, and select Build. 

2. Verify that the Output window shows you where the assembly file is saved on your file 
system, as shown in Figure 7-66. You must resolve any errors for the solution to build. 


Note: If you do not see the Output tab, open it by selecting Debug -» Windows -» Output 
(Microsoft Visual Studio Professional Edition). If you are using Microsoft Visual Studio 
Express Edition, open it by selecting View Output. 



- 

Solution Explorer ^ ^ X 

^Ibm, Broker. Example. ClaimsProcessingBroker. Call' ^ ^ serviceClient 

- 

Q | is | a £ 

□namespace Ibm. Broker. Example. ClaimsProcessingBroker 


^ Solution 'ClaimsProcessingBrokerSolution' (1 project) 


|{ 


3 

- ,JI ClaimsProcessingBrokerProject 

- 

3 

/// <summary> 

i 

0 Oil Properties 



/// ModifyNode Class 


+ References 



/// </sumriiary> 


App.Config 

- 


public class CallWCFNode : NEComputeNode 


r -^\ BuildEmailAttachmentNode.es 



{ 


BuildlncompleteResultsResponseNode , cs 

- 


/// <summary> 


^ CallWCFNode.es 



/// Evaluate Method 


ClaimsProcessingWcfService.cs 



/// </summary> 


Constants.es 



/// <paraim nam e = "input Ass embly' , '></paraiTr> 

3 

GeneratePaymentNode.es 

100% - 


3 



Show output from: Build 


tf I 4 * I ^ I a 


------ Build started: Project: ClaimsProcessingBrokerPro j ectj 

■Con-Figuration: Debug Any CPU 

ClaimsProcessingBrokerProject -> C : YClaimsProcessingFolder 
\ClaimisProcessingBroker5olution\ClaimsProcessingBrokerProject\bin\!Debug 
\ClaimsProcessingBrokerProject , dll 

===== = ==== Build: 1 succeeded or up-to-date^ 9 -failed., U skipped 


R: Error List 


Figure 7-66 Verifying the built assembly file has been saved into the system 
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7.14 Updating the properties for the .NETCompute nodes 


Each .NETCompute node must have a pointer to the assembly (dll) file and the name of the 
class to use. Before the .NET solution was built in Visual Studio, the dll file did not exist. Now 
that the build is performed, you can update the properties for all the Compute nodes. 

1 . In the Message Broker Toolkit, select the CallWCFNode node, and in the Properties view, 
verify that the Assembly name property is specified as follows: 

C:\C1 ai ms Process ingFol der\Cl aimsProcessi ngBrokerSol uti on\Cl aimsProcessi ngBroker 
Project\bi n\Debug\Cl aimsProcessi ngBrokerProject .dl 1 

Specify Cal lWCFNode for the class name, as shown in Figure 7-67. 


.NETCompute Node Properties - CallWCFService 

Description 


Basic 

Wki i.hI Shi irlin 

Assembly name* | C:\ClaimsProcessingFolder\ClaimsProcessingBroker5olution\ClaimsProcessingEirokerProiect\bin\Debug\ClaimsProcessingEirokerProject.dlll 

VIjUuI jluuiu 

Advanced 

Class name [ CallWCFNode 



Figure 7-67 Verifying Assembly name property and node class name 


2. Use this same process to update each .NETCompute node using the values in Table 7-3. 
In our example, <Full Path> is: 

C:\ClaimsProcessingFolder\ClaimsProcessingBrokerSolution\ClaimsProcessingBroker 
Project\bi n\Debug\ 


Table 7-3 Summary of .NETCompute nodes configuration 


Name 

Field 

Path 

BuildlncompleteResultResponse 

Assembly name 

<Full Path>/ 

ClaimsProcessingBrokerAssembly.dll. 

Class name 

BuildlncompleteResultResponseNode 

CallWCFService 

Assembly name 

<Full Path>/ 

ClaimsProcessingBrokerAssembly.dll 

Class name 

CallWCFNode 

GeneratePaymentCanonicalMessage 

Assembly name 

<Full Path>/ 

ClaimsProcessingBrokerAssembly.dll 

Class name 

GeneratePaymentNode 

Gene rateWord Attachment 

Assembly name 

<Full Path>/ 

ClaimsProcessingBrokerAssembly.dll 

Class name 

BuildEmailAttachmentNode 


7.15 Building and deploying the Message Broker application 

Before the Message Broker Application can be used, it needs to be deployed to be built and 
deployed to a broker. WebSphere Message Broker applications are contained in Broker 
Archive (BAR) files that can be deployed to an execution group by dragging and dropping 
from within the Message Broker Toolkit or the WebSphere Message Broker Explorer. 
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Additionally, because this scenario contains .NET code, the .NET assemblies must be built 
and referenced by the message flow. 


7.15.1 Creating the BAR file 

To create the BAR file for deployment: 

1 . Right-click the application in the Broker Development view, and select New h> BAR File. 
Enter ClaimProcessingBarFile as the name of the BAR file, and click Finish. 

2. On the Prepare tab, select ClaimProcessing, and then click the Build and Save button. 

3. Select the Manage tab: 

a. Expand the tree, and select ClaimProcessFlow. 

b. Provide values for the properties: 

• Directory: A directory for file archiving 

• FromEmail: The sender email address 

• TemplateLocation: The location of letter template. 

These steps are highlighted in Figure 7-68. 


Manage 

Rebuild, remove, edit add resources to broker archive and configure their prc 


B? El ® ® Filter by: | <Type filter text> 


Name 

1 Type 

Modified 

□ ClaimProcessing 

Application 

Apr 30, 2012 7:37:15 AM 

- CanonicalXMLNSCToDFDL.map 

MAP file 

Apr 30, 2012 7:37:14 AM 

|l ClaimProcessFlow_Compute.esql 

E5QL file 

Apr 30, 2012 7:37:14 AM 

|l ClaimProcessFlow_Filter.esql 

E5QL file 

Apr 30, 2012 7:37:14 AM 

□ 0 ClairnProcessFlo'A' . cmf 

Compiled message flow 

Apr 30, 2012 7:37:14 AM 

n is ClaimProcessFlow 



+ i ClaimsProcessingCanonicalMessageP 

Library 

Apr 30, 2012 7:37:14 AM 

+ i ClaimsProcessingDFDLMessageForm; 

Library 

Apr 30, 2012 7:37:14 AM 

+ 'i, ClaimsProcessingSOAPImported 

Library 

Apr 30, 2012 7:37:14 AM 

CPl nprii T,-,r =.Ivmi r, 

MAD file 

A I-.K TO -701-7 7.77.1d AM 


Prepare Manage J User Log Service Log 


. Properties ^T\ iZ Problems 


ClaimProcessFlow 


J 


Configure 


(T) Configure properties of selected built resource. 

| c:\temp\testData\FileOut 


Directory 

FromEmail 


| IT50ExampleEmail@itso . example . com 


TemplateLocation || C : \temp\testData\templates\Policy Confirmation . docx 


Figure 7-68 Completing the properties for the flow in the BAR file 


4. Press Ctrl+S to save the BAR file. 


7.15.2 Deploying the BAR file 

The next phase is to deploy the BAR file. To deploy the BAR file: 

1 . Drag the BAR file and drop it into the target execution group, as shown in Figure 7-69 on 
page 361 . 
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Figure 7-69 Drag and drop the BAR file to deploy 


7.16 Testing the WebSphere Message Broker application 

This section outlines testing options to ensure the success of the Message Broker 
application. First, we test the WebSphere MQ interface, and then we test the SOAP interface. 
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7.16.1 Testing the MQ interface 


Additional materials: The completed message flow project includes a Message Broker 
Test Client that defines an Enqueue file for testing the operations exposed by the WCF 
Service. The project interchange file WCFCIient\Project Interchange 
files\ClaimProcessingPl.zip is included in the additional materials for this book. You can 
open a new workspace, import the project interchange, and copy the 
ClaimsProcessingMQTest.mbtest file to the ClaimProcessing application in your own 
workspace. This process creates a Flow Tests folder with the new test client. 



To test the message flow using the MQ transport: 

1 . Delete all files from the WCF Services _BaseDir\customers directory. The _BaseDir 
variable is defined in “Implementing the ICIaimsProcessingWcfService interface” on 
page 210 (see Example 6-41 on page 210) and is set to c:\temp\testData by default. 
Clearing the c:\temp\testData\customers directory ensures that the example data is 
recreated when the WCF service starts. 

2. If there are claims other than CLAIM0001 in the claims subdirectory, such as claims 
created while testing the WCF service with the WCF Test Client in 6.3.9, “Testing the WCF 
Service using the WCF Test Client” on page 235, delete these too. 

3. Stop and restart the ClaimsProcessingWCFService. 

4. If you want to test the CreatePolicy operation, ensure that an smtp server is running and 
that the EmailOutput node is configured to connect to it. 

5. Ensure that the ClaimProcessing application is deployed to your broker and the 
prerequisite queues are defined on the broker’s queue manager. 

6. Double-click ClaimsProcessingMQTest.mbtest in the Flow Tests folder to open the 
Message Broker Test Client in the editor pane. The test client defines a number of 
Enqueue operations that will send a message to the input queue. Each of the Enqueue 
operations corresponds to a different operation on the WCF service. 

The Dequeue events correspond to reading a message from a queue. There are three 
Dequeue events defined to read from the reply queue (OUT), the error queue 
(ERROR_QUEUE), and the payment queue (PAYMENT_QUEUE). 
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Figure 7-70 shows the ClaimsProcessingMQTest Test Client in its initial state. 



Figure 7-70 The ClaimsProcessingMQTest Message Broker Test Client in its initial state 

7. The Message Broker Test Client allows some common configuration options to be applied 
across all Enqueue and Dequeue operations in the client. In this instance, all requests 
must have a valid ReplyTo queue set so that the flow knows where to send the response. 
As shown in Figure 7-71 on page 364, the OUT queue is specified as the ReplyTo queue 
name for all operations by setting it in the MQ Default Header. This causes the Message 
Broker Test Client to populate the MQMD with the ReplyTo queue. 
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E aimsProcessingMQTest £3 \ = Q 

Configuration 


Test Client Configuration 

^§3 Message Flows 
Deployment 
MQ Settings 
JI ^ JMS Settings 

□ MQ Message Headers 

[HQ. MQ Message Header ’'Default Header” 

□ ^ JMS Message Headers 

JMS Message Header 'Default Header” 


Events Configuration 


▼ MQ Message Header "Default Header" 




Accounting token: 

Message type: g 

Application origin data: 

Message sequence number: j 

Application id data: 

Offset: | o 

Backout count: q 

Original length: 

Character set: q 

Persistence: 2 

Correlation id: 

Priority: 

Encoding: q 

Put application name: 

Expiry: | 

Put application type: g 

Feedback: q 

Put date/time: 

Format: 

Report: g 

Group id: 

Reply to queue manager name: I - 

Message id: 

Reply to queue name: qut 

Message flags: q 

User id: 




dl Indude RFH V2 header 


0 


Figure 7-71 Configuring the default MQMD for all enqueue and dequeue operations 


Testing the ViewOutstandingClaims operation 

To test the ViewOutstandingClaims operation: 

1 . Locate the enqueue named ViewOutstandingClaims. The name is in the General 
Properties section. 

2. Modify the connection properties to refer to your broker. Because the Message Broker 
Client uses the MQ Java Client to connect, the port must correspond to a running listener 
on the broker’s queue manager. 

3. The input message is displayed in the Message section. When working with binary 
message types, it can be useful to view the data as hexadecimal by checking the Show in 
hexadecimal viewer check box, as shown in Figure 7-72 on page 365. 
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Figure 7-72 The ViewOutstandingClaims Enqueue 

4. Click Send Message to send the message to the IN queue. 

A message is displayed below the Enqueue file saying that a message was sent to MQ 
queue IN, as shown in Figure 7-73. If there was a problem putting the message on the 
queue, an error message appears here instead. 



Figure 7-73 Confirmation that the message has been sent to MQ 

5. The message is now processed by the ClaimsProcessing flow, and a message is put on 
the Reply queue. Locate the Dequeue corresponding to the OUT queue, as shown in 
Figure 7-74 on page 366. 
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Figure 7-74 The Dequeue for the OUT queue 


6. Click Get Message. 

7. If you receive an Error message indicating that the OUT queue was empty (shown in 
Figure 7-75), check the Exception trace. 

If you see the text com. i bm.mq.MQException: MQJE001: Completion Code '2', Reason 
1 2033 ' . , the message flow has not yet finished processing the message, so there is no 
message to get on the OUT queue. This is more likely to happen on the first invocation of 
the message flow that initializes the WCF client and the service instance. If this happens, 
simply wait for a few seconds, and click the Get Message button again. 
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Events Configuration 


Figure 7-75 An MQRC 2033 error indicating that the OUT queue was empty 
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If a message is present, you will see an MQ Queue Monitor OUT element created under 
the Dequeue. The contents of the received message are displayed in the Message panel 
to the right, as shown in Figure 7-76. Here the REPLYCC completion code was 0, 
indicating that the operation was successful and the CLAIM details for CLAIM0001 are 
returned as the only element in the CLAIMLIST. 
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Figure 7-76 The ViewOutstandingClaims response message 


Testing the ViewClaims operation 

To test the ViewClaims operation: 

1 . Locate and select the Enqueue named ViewClaim to open it in the Message panel. 

2. Click the Send Message button. 

A confirmation that the message was sent to MQ appears underneath the Enqueue, as 
shown in Figure 7-77 on page 368. 
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Figure 7-77 The ViewClaim Enqueue 


3. Return to the Dequeue for the OUT queue, and click the Get Message button. 

The details of CLAIM0001 are displayed in the Message panel, as shown in Figure 7-78. 
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Figure 7-78 The ViewClaim response showing CLAIM0001 
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To test the ViewClaim method using an invalid input: 

1 . Locate and select the Enqueue named ViewInvalidClaim. 

2. In this case, we make a request to view the claim CLAIM101 that does not exist in the 
system, so we expect an error. 

3. Click the Send Message button. 
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You will see a confirmation that the message was sent, as shown in Figure 7-79. 
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Figure 7-79 The ViewInvalidClaim Enqueue 


4. Select the Dequeue associated with the OUT queue, and press the Get Message button. 

You will see a response with a REPLYCC completion code indicating that there was an 
error. The error text will note that an error was written to the error queue. The response to 
the OUT queue is shown in Figure 7-80. 
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Figure 7-80 An error response 


5. In the case of an error, the message flow writes an error message to the 

ERROR_QUEUE. Locate the Dequeue corresponding to the ERROR_QUEUE, and press 
the Get Message button. 


Chapter 7. Scenario: Integrating Windows Communication Foundation in message flows - Part 2 369 


A message is displayed with the error list encountered by the broker. You can view this as 
an XML structure and scroll to see that the error code and message set by the WCF 
service are included in the error message, as shown in Figure 7-81. 
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Figure 7-81 The error message contains the customer fault message and error code fields 


Testing the ViewPolicy operation 

To test the ViewPolicy operation: 

1 . Locate and select the Enqueue file named ViewPolicy. 

2. Click Send Message. 

You should see a confirmation that the message was sent appear underneath the 
Enqueue, as shown in Figure 7-82 on page 371. 
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Figure 7-82 The ViewPolicy Enqueue 


3. Select the Dequeue corresponding to the OUT queue, and press the Get Message 
button. 

You will see a response on the OUT queue with a completion code of 0 indicating success 
and the details for POLICYOOOI attached in the POLICYLIST, as shown in Figure 7-83. 
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Figure 7-83 The response from the ViewPolicy operation 


Testing the CreatePolicy operation 

The CreatePolicy operation sends an email to the customer on successful completion of the 
operation. To run this step, you must ensure that you have a local smtp server running and 
that the EmailOutput node is configured to access it. 
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To test the CreatePolicy operation: 

1 . Select the Enqueue named CreatePolicy. Note the terminator character for the list of 
Named Parties and the list of Other Names in the binary message. 

2. If you want to see the email document produced, replace the email address 
johndoe@itso.example.ibm.com with your own email address. 

3. Press the Send Message button. 

You will see a confirmation message indicating that the message was sent, as shown in 
Figure 7-84 



Figure 7-84 The CreatePolicy Enqueue 


4. Select the Dequeue corresponding to the OUT queue. 

5. Click Get Message. 

6. The Message panel in the Dequeue will display a successful completion code of 0 and 
return the policy information including the new policy reference, as shown in Figure 7-85 
on page 373. 
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Figure 7-85 The response from the CreatePolicy operation 


7. If you configured your own email, you will receive an email with the Policy confirmation 
document attached. 

8. The CreatePolicy operation also causes a file to be written to the output directory that you 
configured in 7.15, “Building and deploying the Message Broker application” on page 359. 
By default, this directory is C:\temp\testdata\fileOut. If you check this location, you will see 
a .docx file named PolicyConfirmation<Date>.docx. A sample document is shown in 
Figure 7-86 on page 374. 
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|ITSO Insurance 
Department Building 123 
123 Main St. 

Any City, Any State USA 


Doe, John 


Policy Number: 

POLICY35d035ac0ab045e796108f2305819b95 

Coverage Period: 

27 March 2012 
through 
27 March 2013 

12:01 a.m. local time at the address of the name insured. 


27 March 2012 


Dear Doe, John 

Thank you for choosing us to meet your insurance need. We appreciate the opportunity to 
provide you this valuable coverage. We're here for you 24/7, 365 days a year. 

We value you as our policyholder and look forward to serving your insurance needs for many 
years to come. If you have any questions, please contact ITSO at itsoinsurance.com or 
1-800-ITSOINS. We will be happy to help you. 


Sincerely, 

ITSO Insurance 
Enclosure 


Figure 7-86 Sample document sent by the CreatePolicy operation 


Testing the CreateClaim operation 

We use the CreateClaim operation to create a second claim in the system so that in the next 
two steps we can approve one claim and reject the other. To create the CLAIM0002 claims 
using the Message Broker Test Client, follow these steps: 

1 . Select the CreateClaim Enqueue. Note that the claim specifies the claim reference to be 
created as CLAIM0002. 

2. Click Send Message. 

You will see a confirmation that the message was sent to the MQ queue appear below the 
Enqueue, as shown in Figure 7-87 on page 375. 
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Figure 7-87 The CreateClaim Enqueue 

3. Select the Dequeue for the OUT queue. 

4. Click Get Message. 

The response message shows a completion code of 0, indicating that the claim was 
created successfully, as shown in Figure 7-88 on page 376. 
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Figure 7-88 CreateClaim response 

Test the ApproveClaim operation 

Use the ApproveClaim operation to approve the CLAIM0001 claim. To test the ApproveClaim 
operation: 

1 . Select the ApproveClaim Enqueue. 

2. Click Send Message. 

A confirmation will appear below the Enqueue, showing that the message was put on the 
MQ queue, as shown in Figure 7-89 on page 377. 
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Figure 7-89 The ApproveClaim Enqueue 

3. Select the Dequeue for the OUT queue. 

4. Click Get Message. 

The response will show a completion code of 0, indicating successful completion, as 
shown in Figure 7-90 on page 378. 
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Figure 7-90 The ApproveClaim response 

5. The ApproveClaim operation also generates a payment message in the Canonical 
Message Format to send to a payment processing system. Select the Dequeue for the 
PAYMENT_QUEUE queue, and click Get Message. 

You can view the received message with the XML viewer to see the payment request, as 
shown in Figure 7-91 on page 379. 


378 


Using WebSphere Message Broker V8 in Mid-Market Environments 


Hi| ^ClaimsProcessingMQTest £3 

Events 

Message Fbw Test Events 


eUDF m e iff 


0 ^ Enqueue 

mq. Message sent to MQ Queue ’IN' 1 
□ Sp Dequeue 

ifS. MQ Queue Monitor ’OUT 
rriq MQ Queue Monitor ’OUT 
nS. MQ Queue Monitor ’OUT 
nS. MQ Queue Monitor ’OUT 
MQ Queue Monitor ’OUT’ 

MQ Queue Monitor ’OUT 
rriq MQ Queue Monitor ’OUT’ 

0 Dequeue 

jj§. MQ Queue Monitor TRRORjQUEUE" 

0 ^ Enqueue 

mq. Message sent to MQ Queue IN’ 

0 Enqueue 

mq. Message sent to MQ Queue ’IN’ 

0 ^ Enqueue 

mq. Message sent to MQ Queue ’IN’ 

0 ^ Enqueue 

mq. Message sent to MQ Queue ’IN’ 

0 ^ Enqueue 

mq. Message sent: to MQ Queue ’IN’ 

0 Enqueue 

mq. Message sent to MQ Queue ’IN’ 

1 ^ Enqueue 
0 Dequeue 

mq. MQ Queue Monitor ’PAYMENT_QUEUE’ 


► General Properties 
T Detailed Properties 


Host: 

Port: 


localhost 


2408 


Queue manager: BRK3 

Queue: 

Message — 

► Header 


PAYMEMT_QUEUE 


Body: View as XML structure 


Name 

Value | 

0 NSliCanonicalMessage 


xmlnsiNSl 

http://www.ibm.tDm/VVebSphereMes5ageBr0ker/EHam, . . 

0 NSfcHeader 


Appld 


Msgld 

414d 5 12042 524b 33202Q2Q2Q202Q20207b79724f2Q00 , . . 

Command 


BusinessUnit 


BusinessUnitCodi 


ReplyQueue 

OUT 

ReplyToQm 

BRK8 

0 ApplicationMessage 


0 PaymentRequesI 


0 Payment 


Amount 

250 

0 Custome 


Custi 

CUST00QQ3 

Firstt 

Jane 

0 Othe 


b 

Jill 

b 

Jenny 

Sum: 

Doe 

Addr 

1 Generic Street, Any Town, USA 

Email 

janedoe @itso . example . ibm . com 

Underwri 

Partner Insurance Company A 

0 NS 1 trailer 


Created 

20 12-Q3-27T 23 : 09 : 24 

LastModified 

20 12-0 3-2.7T23 : 09 : 24. 39062 5 

LastModifiedBy 

WebSphere Message Broker 8. 0.0.0 - BRKS.ClaimProce. . . 


Events Configuration 


Figure 7-91 The payment request generated by the ApproveClaim operation 


Testing the RejectClaim operation 

In “Testing the CreateClaim operation” on page 374, you created a second claim with claim 
reference CLAIM0002. To use the RejectClaim operation to reject this claim, follow these 
steps: 

1 . Select the RejectClaim Enqueue. 

2. Click Send Message. 

A confirmation will appear below the Enqueue showing that the message was sent to the 
MQ queue, as shown in Figure 7-92 on page 380. 
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Figure 7-92 The RejectClaim Enqueue 


3. Select the Dequeue for the OUT queue. 

4. Click Get Message. 

The response message shows a completion code of 0, as shown in Figure 7-93 on 
page 381 . 


380 Using WebSphere Message Broker V8 in Mid-Market Environments 



Figure 7-93 The RejectClaim response 

7.16.2 Testing the SOAP Interface 

Recall from the scenario overview that in addition to the MQ interface that connects to the 
insurance company’s existing messaging infrastructure, the flow also hosts a SOAP request 
that forms the basis of a web service that allows customers to check the status of their claim 
online. 


Additional materials: The ClaimsProcessingSOAPImported project in the additional 
materials for this book includes a Message Broker Test Client that can be used to test the 
SOAP interface. 
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To test the SOAP interface: 

1 . Double-click the SOAPTest.mbtest Message Broker Test Client to open it in the editor. 

2. The SOAPTest Test Client already has a message flow Invoke operation defined that will 
send a SOAP message to the broker listener to view the status of the CLAIM0001 claim. 

3. Select the Configuration tab, and set the deployment options to refer to your local broker, 
as shown in Figure 7-94. 
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Figure 7-94 Configuring the SOAP Test Client 


4. Return to the Events tab, as shown in Figure 7-95 on page 383. The message content is 
already filled in so that the ViewClaim operation looks up the claim details for CLAIM0001 . 
Click Send Message. 

The Test Client is set for manual deployment. However, you might see an information 
message saying that the deployment was metallized. Ignore this. 

The Test Client sends the message to the http://localhost:7800/ClaimsProcessing end 
point and listens for a response. 

When a response is received, you will see a SOAP message displayed in the right panel of 
the test client, as shown in Figure 7-95 on page 383. 
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Figure 7-95 Output from the SOAP Test Client 


7.17 Altering the scenario to use a SOAP over HTTP based 
binding 


One of the main benefits of the WCF framework is that the choice of transport is decoupled 
from the application logic. It is therefore possible to update the service to use a web services 
based transport without having to change any of the code. 


7.17.1 Altering the WCF Service to expose an http based binding 

We use the WCF Service Configuration Editor to add a new service endpoint for the WCF 
service, which uses the basicHttpBinding to expose a new endpoint to the 
ClaimsProcessingWcfService. 

To enable the basicHttpBinding endpoint: 

1 . In Visual Studio, launch the WCF Configuration Editor by selecting Tools -> WCF Service 
Configuration Editor. 

2. Select File -» Open -» Config File. 
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3. Navigate to the App.Config for the WCF service in the Open Dialog, and click the OK 
button. 

4. Expand the Services -> 

Ibm.Broker.Example.ClaimsProcessing.ClaimsProcessingWcfService -> Endpoints 

tree node. 

5. Select the Endpoint folder, right-click and select New Service Endpoint. 

6. In the Name field, enter WebServi cesEndpoi nt. 

7. In the Address field, enter /WebServi ces. 

8. In the Binding field, enter basicHttpBinding. 

9. In the Contract field, enter 

Ibm. Broker. Exampl e.Cl aims Process i ng. IC1 aimsProcessi ngWcfServi ce. 

The completed Service Endpoint definition will match the example in Figure 7-96. 



Figure 7-96 Adding the WebServices endpoint 

10. Select File -» Save. 

After you save the file, open the App.Config in the code editor by double-clicking its icon in the 
Solution Explorer. You will see that the WCF Configuration Editor added the endpoint 
definition shown in Example 7-59 to your file. 

Example 7-59 The WebServices endpoint definition 

<endpoi nt address="/WebServices" bi ndi ng="basi cHttpBi ndi ng" 
bi ndi ngConf i gurati on=" " 

name= "WebServi ces Endpoint" 

contract="Ibm. Broker. Exampl e.Cl aimsProcessi ng. I Cl aimsProcessi ngWcfServi ce" /> 


Recall that the endpoint address is relative to the base address of the application, so the new 
endpoint is available on the 

http: //local host: 8732/Cl ai msProcessi ngWcfServi ce/WebServi ces URI. 

To make the new endpoint available, relaunch the service using the Debug Start Without 
Debugging menu item. Visual Studio automatically hosts the WCF and launches the WCF 
Test Client, as usual. Notice that there are two endpoints defined, the TcpIpEndPoint and the 
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WebServicesEndpoint. You can test the operations on the WebServicesEndpoint in exactly 
the same way as you did in 6.3.9, “Testing the WCF Service using the WCF Test Client” on 
page 235 for the TcpipEndPoint. Figure 7-97 shows an example of invoking the ViewClaim 
operation from the WebServicesEndpoint. 



Figure 7-97 The WCF Test Client displays both endpoints 


7.17.2 Altering a message flow to use an HTTP based binding 

In this section, you alter a message flow in WebSphere Message Broker to access the service 
with an FITTP-based binding. To follow this section, you must have already modified the WCF 
service to use basicHttpBinding, as discussed in section 7.17.1 , “Altering the WCF Service to 
expose an http based binding” on page 383. 

To modify the message flow to use the basicHttpBinding, we must alter the configuration file 
for the assembly used by the broker. Locate the folder containing the 
ClaimsProcessingAssembly.dll, ClaimsProcessingBrokerAssembly.dll.config, and 
ClaimsProcessingBrokerAssembly.pdb files. Open the config file in a text editor. The content 
must match the example shown in Example 7-60. 

Example 7-60 The ClaimsProcessingBrokerAssembly.dll.config file 

<?xml version="1.0" encodi ng="utf-8"?> 

<configuration> 

<system. servi ceModel > 

<bi ndi ngs> 
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<netTcpBi ndi ng> 

<binding name =l, TcpIpEndPoi nt" closeTimeout= l, 00:01:00 M 
openTimeout="00:01 :00" 

recei veTimeout="00: 10:00" sendTimeout= M 00:01 : 00 " transacts on FI ow="fal se" 
transferMode= l, Buffered M transacti onProtocol ="01 eTransacti ons" 
hostNameCompari sonMode="StrongWi 1 dcard" 1 i stenBackl og=" 10" 
maxBufferPool Si ze= 11 524288" maxBufferSi ze= 11 65536 11 maxConnecti ons= l, 10" 
maxRecei vedMessageSi ze= 11 65536 "> 

<readerQuotas maxDepth="32 M maxStri ngContentLength= l, 8192" maxArrayLength=" 16384" 
maxBytesPerRead= l, 4096 M maxNameTableCharCount= l, 16384 11 /> 

<rel iableSession ordered= M true M inacti vi tyTimeout="00: 10:00" 
enabl ed="fal se" /> 

<security mode= l, Transport ll > 

<transport cl ientCredentialType= l, Windows M protectionLevel = l, EncryptAndSign M /> 
<message cl ientCredentialType="Windows" /> 

</security> 

</bi ndi ng> 

</netTcpBinding> 

</bindings> 

<cl ient> 

<endpoi nt address="net . tcp://l ocal host : 8523/ 11 bi ndi ng="netTcpBi ndi ng" 
bi ndi ngConfi gurati on="TcpIpEndPoi nt" contract=" I Cl aims Process i ngWcfServi ce" 
name =l, TcpIpEndPoi nt"> 

<identity> 

<userPri nci pal Name value= l, DAVICRIGW500\davicrig M /> 

</identity> 

</endpoint> 

</cl ient> 

</system. servi ceModel > 

</confi gurati on> 


Remove the <endpoint> element and all of its children from the <client> element, and replace 
it with the endpoint definition shown in Example 7-61 , which refers to the WebServices 
endpoint. 

Example 7-61 The client endpoint definition 

<endpoi nt address="http: //I ocal host : 8732/Cl aims Process i ngWcfServi ce/WebServi ces" 
bi ndi ng="basi cHttpBi ndi ng" 
bi ndi ngConfi gurati on= "WebServi cesEndpoi nt 11 

contract=" IC1 aimsProcessi ngWcfServi ce" name="WebServi cesEndpoi nt" /> 


The endpoint definition refers to the WebServicesEndpoint bindingConfiguration. This 
bindingConfiguration supplies configuration information for the binding. To add this element, t 
delete the <netTcpBinding> element and all of its children and replace it with the 
bindingsConfiguration shown in Example 7-62. 

Example 7-62 The configuration for the basicHttpBinding 
<basi cHttpBi ndi ng> 

<bi nding name= "WebServi cesEndpoi nt" cl oseTimeout="00:01 :00" 
openT i meout= "00 : 01 : 00 11 

recei veTimeout="00: 10:00" sendTimeout="00:01 :00" al lowCookies="fal se" 
bypassProxyOnLocal ="fal se" hostNameCompari sonMode="StrongWi 1 dcard" 
maxBufferSi ze="65536 11 maxBufferPool Size="524288" 
maxRecei vedMessageSi ze= 11 65536 11 
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messageEncodi ng= l, Text 11 textEncodi ng= M utf-8" transferMode= l, Buffered" 
useDefaul tWebProxy= l, true l, > 

<readerQuotas maxDepth="32" maxStri ngContentLength= l, 8192" 
maxArrayl_ength=" 16384" 

maxBytesPerRead= l, 4096 M maxNameTableCharCount=" 16384" /> 

<security mode= l, None ll > 

<transport cl ientCredentialType= l, None 11 proxyCredentialType= l, None 11 
real m= 11 11 /> 

<message cl ientCredentialType= l, UserName 11 algorithmSuite="Defaul t" /> 
</security> 

</bi ndi ng> 

</basi cHttpBi ndi ng> 


The completed ClaimsProcessingBrokerAssembly.dll. config file must match the example 
shown in Example 7-63. 

Example 7-63 The completed ClaimsProcessingBrokerAssembly.dll.config file 

<?xml version= M 1.0" encodi ng="utf-8"?> 

<configuration> 

<system . servi ceModel > 

<bi ndi ngs> 

<basi cHttpBi ndi ng> 

<bi ndi ng name= "WebServi cesEndpoi nt 11 cl oseT imeout= M 00 : 01 : 00" 
openTimeout= M 00:01:00 M 

recei veTimeout="00: 10:00" sendTimeout="00:01 :00" al 1 owCooki es="fal se" 
bypassProxyOnLocal ="fal se" hostNameCompari sonMode="StrongWi 1 dcard" 
maxBufferSi ze= l, 65536" maxBufferPool Si ze= l, 524288 M 
maxRecei vedMessageSize= l, 65536 M 

messageEncodi ng= l, Text 11 textEncodi ng="utf-8" transferMode= l, Buffered M 
useDefaul tWebProxy= l, true ll > 

<readerQuotas maxDepth= l, 32 M maxStri ngContentLength= l, 8192 M 
maxArrayLength= 11 16384" 

maxBytesPerRead="4096" maxNameTabl eCharCount=" 16384" /> 

<security mode="None"> 

<transport cl ientCredential Type="None" proxyCredenti al Type="None" 
realm="" /> 

<message clientCredentialType="UserName" algorithmSuite="Defaul t" /> 
</security> 

</bi ndi ng> 

</basi cHttpBi ndi ng> 

</bi ndi ngs> 

<cl ient> 

<endpoint address=" http: //local host: 8732/Cl ai ms Processi ngWcf Servi ce/WebServi ces" 
bi ndi ng="basi cHttpBi ndi ng" bi ndi ngConfi gurati on= "WebServi cesEndpoi nt" 
contract=" IC1 aimsProcessi ngWcfServi ce" name="WebServi cesEndpoi nt" /> 
</cl ient> 

</sys tern. servi ceModel > 

</confi gurati on> 


When you save the file you can see a BIP7451 message in the Event Viewer indicating that a 
host swap deploy was successful, as shown in Figure 7-98 on page 388. 
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Figure 7-98 Changing the config file causes Broker to perform a hot swap deploy 

The changes are picked up by WebSphere Message Broker immediately without needing to 
redeploy the flow or change any of the code. You can now test the message flow using the 
Message Broker Test Client using the same procedure that you used in section7.1 6.1 , 
“Testing the MQ interface” on page 362. 

In Figure 7-99 on page 389, we used the ViewClaim enqueue to send a ViewClaimRequest 
message to the flow. 
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Figure 7-99 Sending a ViewClaimRequest to the message flow 


The response from this message can be viewed using the Dequeue for the OUT message, as 
shown in Figure 7-100. 
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Figure 7-100 Using the Dequeue for the OUT queue to confirm the message was processed successfully 


The message flow is now successfully using the basicHttpBinding binding to make WCF calls 
to the service. 
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Integrating file transfer with 
WebSphere MQ FTE into the 
message flow 


The scenario in this chapter illustrates the use of WebSphere Message Broker to intercept 
files routed by WebSphere MQ File Transfer Edition, analyze and split that file into multiple 
files, and route those files to their appropriate destination. It also illustrates processing replies 
from the processing systems and collecting those replies into one message to send back to 
the originating system. 

This scenario illustrates receiving files from WebSphere MQ File Transfer Edition into a 
message flow, inspecting and splitting those files, and then routing the files to multiple 
destinations and aggregating the replies. It also illustrates how to access .NET code directly 
from ESQL and how to use the DFDL editor to model message data format. 

This chapter contains the following topics: 

► Scenario overview 

► Overview of the WebSphere MQ File Transfer edition 

► Preparing the broker environment for this scenario 

► Applications emulated in this scenario 

► Creating the main message flow 

► Running the scenario 

► Extending the scenario 


Additional materials: You can download the WebSphere Message Broker project 
interchange file and the .NET class code for this scenario from the IBM Redbooks 
publication web site. See Appendix A, “Additional material” on page 485 for more 
information. 


© Copyright IBM Corp. 2012. All rights reserved. 
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8.1 Scenario overview 


An investment firm has a number of branches that handle the day-to-day stock transactions of 
their customers. As each transaction is executed, a record of the transaction is created. At the 
end of the day, a summary report of the transactions is created and the branch stores the 
transaction records (referred to as operations) and the summary report into one consolidated 
file. The consolidated file is then transferred from the branch over WebSphere MQ FTE to a 
message flow for processing at the firm’s head office. 

The message flow receives the consolidated file and parses the entries in the file. The 
summary report record in the file is sent as a message to the Report Data Warehouse (RDW) 
over WebSphere MQ. The transaction records in the file are handled by a .NET assembly and 
sent to the Volume Analysis System (VAS) application for processing. As the RDW and VAS 
process the records sent to them, they send a reply back to the message flow. These replies 
are aggregated into one reply for the branch so that it can verify that each transaction was 
handled. 

In addition to routing the files, the message flow tracks the status of the delivery and 
processing by recording the following events: 

► A file is received by the message flow 

► The messages are sent to their destination 

► Each destination application receives and processes a message 

► All messages from the original file have been received and processed by their destination 



This scenario assumes that you have the following prerequisites: 

► WebSphere MQ File Transfer Edition V7.0 

► WebSphere Message Broker version 8. 0.0.0 or higher installed 

► WebSphere Message Broker Toolkit version 8.0. 0.0 or higher installed 
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► A message broker defined on the local machine with a corresponding WebSphere MQ 
queue manager 

► An SMTP email server running on the local host or access to an SMTP server for sending 
outbound email 

► Microsoft Visual Studio 2010 installed 


8.2 Overview of the WebSphere MQ File Transfer edition 

WebSphere MQ File Transfer Edition V7.0 (FTE) delivers a reliable, managed file transfer 
solution for moving files between IT systems without the need for programming. Files that are 
larger than the maximum individual WebSphere MQ message size can be moved. A log of file 
movements demonstrates that business data in files is transferred with integrity from a source 
file system to a destination file system. 

Using the WebSphere MQ File Transfer Edition nodes offers seamless integration with your 
existing WebSphere MQ File Transfer Edition network. Figure 8-2 shows a typical WebSphere 
MQ File Transfer Edition network. 



The main components and concepts of WebSphere MQ File Transfer Edition are: 

► Agent: A process that forms the endpoint of a transfer (source or destination). An agent is 
a WebSphere MQ application and is connected to one queue manager. Many agents can 
be connected to the same queue manager. Operational commands can be sent to an 
agent (for example, to request a transfer) by putting an XML message on a particular 
queue on the agent's queue manager. 

► Coordination queue manager: One queue manager in the topology takes on the 
responsibility of the coordination queue manager. All agents register with the coordination 
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queue manager and also send audit information about each transfer. The coordination 
queue manger is responsible for publishing that audit information to external monitoring 
applications. 

► Transfer: A transfer is a movement of one or more files from one agent to another. The 
transfer goes directly from one agent's queue manager to the other agent's queue 
manager, not through the coordination queue manager. The transfer takes place even if 
the coordination queue manager is not running. 

► Transfer log: The WebSphere MQ Explorer plug-in tool includes a Transfer Log view that 
subscribes to the coordination queue manager for the audit information. The view displays 
information about every transfer that occurs in a given topology. 

Most of the file transfers occurred in a peer-to-peer way, although there is a feature to use 
agents in one-to-many ways, as shown in this website: 

http://www.i bm.com/devel operworks/websphere/1 i brary/techarti cl es/1103_cul 1 en/1103_ 
cul len.html 

But to make complex tasks in the middle of file transfers, it is better to use WebSphere 
Message Broker. 


8.2.1 Using WebSphere Message Broker as a bridge for FTE networks 

One of the possible approaches when constructing an FTE network when using the broker is 
to have the broker as a central agent on the coordination queue manager and have many 
stand-alone FTE agents on other machines. See Figure 8-3. 
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With this design the stand-alone agents can either directly transfer their files to other agents 
or transfer them to the central broker agent, which can do any required processing before 
transferring it on to another agent or, if required, sending it to another system using a different 
transport protocol, such as HTTP, FTP or WCF.NET. It also allows for transformation of data 
before being sent to an end destination. 

In this scenario, we demonstrate how you can use the broker with a file transfer to execute 
essential processing steps and route message between separate FTE agents. 


8.3 Preparing the broker environment for this scenario 

Before any other resources are configured for this scenario, ensure that there is an MQ 
Manager and a broker created at the local machine. 

In this chapter, we use following naming conventions: 

► QMJTSO is the name of the queue manager used both for the broker and a stand-alone 
MQ FTE agent from the Branch application emulator. See 8.4.1, “Branch application 
(FTE)” on page 403. 

► BFIKJTSO is the name of the broker. 

► ITSO is the name of the default execution group. 

► MOCKS is the name of the execution group for mock flows of the Report Data Warehouse 
and Volume Analysis System applications. See 8.4.2, “Report Data Warehouse” on 
page 409 and 8.4.3, “Volume Analysis System” on page 414 respectively. 

Use the following procedure to create the WebSphere Message Broker resources: 

1 . In the Message Broker Toolkit, right-click Brokers in the Brokers tab. Select New -» Local 
Broker. 

2. In the New Local Broker dialog, enter: 

- BRK_ITS0 as the name of the new broker 

- QM_ITS0 as the queue manager name for the broker 

- Local System as the user name 

- ITSO as the name of the default execution group, as shown in Figure 8-4 on page 396 
Click Finish. 
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Figure 8-4 Preparing the broker for the FTE scenario 

The Message Broker Toolkit creates a WebSphere MQ manager, broker, and the 
execution group. 

3. In the Brokers view, right-click the BRKJTSO broker, and select New Execution Group. 
Enter MOCKS as a name for new execution group, as shown in Figure 8-5, and then click 

OK. 


!□ New Execution Group 


Enter the name of the new execution group: 
1 MOCK5| 


OK 


Cancel 


Figure 8-5 Creating a new execution group 


Other resources: There are a set of other resources that are used within this scenario. 
These resources are explained and created later on, together with respective parts of the 
scenario. 


8.3.1 Creating the database 

This scenario uses a Microsoft SQL Server 2008 database. This section provides information 
about creating the database. 
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Configuring SQL Server network connectivity services 

Use the following procedure to configure the SQL Server network connectivity services: 

1 . Open the SQL Configuration Manager by clicking Start All Programs -» Microsoft 
SQL Server 2008 -» Configuration Tools -» SQL Server Configuration Manager. 

2. Select SQL Server Network Configuration Protocols for SQLEXPRESS in the left 
column, and ensure that the Named Pipes and TCP/IP protocols are both enabled 
(Figure 8-6). If they are not, enable them by right-clicking the protocol and selecting 

Enable. 


5QL Server Configuration Manager (Local) 

Protocol Name 
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J SQL Server Services 

"IT Shared Memory 

Enabled 

_J_ SQL Server Network Configuration (32bit) 
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E SQL Native Client 10.0 Configuration (32bit) 

IP TCP/IP 
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Aliases 

E 5QL Server Network Configuration 

5L 

+] ^ SQL Native Client 10.0 Configuration 

IT via 
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Figure 8-6 SQL Server Network Configuration window 


3. Select SQL Server Services in the same window, and ensure that the browser is running 
(Figure 8-7). 
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Figure 8-7 Run the SQL Server Browser service 


If the browser is not running, start it by right-clicking it and selecting Start. If you cannot 
start it in this way, use the following steps: 

a. Right-click the browser, and select Properties. 

b. Select the Service tab in the SQL Server Browser Properties dialog, and select Start 
Mode. See Figure 8-8 on page 398. 

c. Open the drop-down box, and select Manual. Click OK. 

d. Right-click the browser, and select Start. 
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Figure 8-8 Change the start mode of SQL Server Browser service 


Creating an ITSO database server instance 


Tooling: In this and the next section, we use Visual Studio to administer SQL Server. 


Use the following procedure to create a database server instance in Visual Studio: 

1 . Open Visual Studio by clicking Start ->• All Programs -» Microsoft Visual Studio 
2010 -» Microsoft Visual Studio 2010. 

2. Click View -» Server Explorer to open the Server Explorer view. 

3. Right-click Data Connection, and select Add Connection. 

4. In the Choose Data Source window, select Microsoft SQL Server, and click Continue. 

5. In the Add Connection window: 

a. Select Microsoft SQL Server (SqlClient) in the Data source field. 

b. Select the server in the Server name drop down. 

c. Select the log on method, and enter your credential if required. 

d. In the Connect to a database section, enter the name for the new database in the 
Select or enter a database name field. In this case, enter ITSO as the database name. 

e. Click OK. 

Creating a FILE_STATUS table and indexes 

After creating the database, you create a FILE_STATUS table there. This table is used within 
the scenario for logging purposes. You can use the script in Example 8-1 . 

Example 8- 1 Sample script to create a FILE_STATUS table 

IF NOT EXISTS (SELECT * FROM sys. objects WHERE objectjd = 

OBJ ECT_I D ( N ' [dbo] . [FILE_STATUS] ' ) AND type in (N 1 U ' ) ) 
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BEGIN 

CREATE TABLE [dbo] . [FILE_STATUS] ( 

[id] [int] IDENTITY(l.l) NOT NULL, 

[filename] [nvarchar] (64) COLLATE SQL_Lati nl_General_CPl_CI_AS NOT NULL, 
[parts_in_total] [int] NOT NULL, 

[parts_processed] [int] NOT NULL, 

[completed] [bit] NOT NULL, 

[record_time] [datetime] NOT NULL, 

[1 ast_modi tied] [datetime] NOT NULL, 

[report_msg_id] [nchar] (51) COLLATE SQL_Lati nl_General_CPl_CI_AS NULL, 
CONSTRAINT [PK_FILE_STATUS] PRIMARY KEY CLUSTERED 

( 

[id] ASC 

) WITH (PADJNDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, 
ALLOW_ROW JOCKS = ON, ALLOWJAGE JOCKS = ON) 

) 

END 

GO 

IF NOT EXISTS (SELECT * FROM sys. indexes WHERE objectjd = 

OBJ ECT_I D ( N ' [dbo] . [FI LE_STATUS] 1 ) AND name = N' IX_FILE_STATUS 1 ) 

CREATE UNIQUE NONCLUSTERED INDEX [IX_FILE_STATUS] ON [dbo] . [FILE_STATUS] 

( 

[report_msg_id] ASC 

) WITH (PADJNDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORTJNJEMPDB = OFF, 
IGNORE_DUP_KEY = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, 
ALLOW_PAGE_LOCKS = ON) 

GO 


Note: In our scenario, we use SQL Server as an RBMS, so all scripts are tested for that 
particular product. For other RDBMS, the syntax varies. 

The description of columns is as follows: 

► Id: The primary key, auto generated. 

► File_name: The name of the transferred file containing the report. 

► PartsJn_total: The number of operations contained plus one summary report within the 
file. 

► Parts_processed: The number of responses received from integrated systems, such as 
RDW and VAS. 

► Completed: The flag that became true when all of the parts of the file are processed by 
RDW and VAS. 

► Record_time: The time when the broker started to process this report. 

► Last_modified: The time of the last modification of this row. 

► Report_msgJd: Used as a temporary storage to correlate responses from RDW with rows 
in this table. 


FILE_STATUS script: In addition to creating a table, this script also creates a primary key 
and index to speed up access to this table through the i d and report J d columns. This is a 
good approach to think about indexes for every new table from the beginning, even if you 
only create this table for sample purposes. 
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Use the following procedure to create and execute a script: 

1 . To execute a script, open a new SQL Script Editor window by selecting Data -» Transact 
SQL-Editor ->• New Query connection. 

ITSO database instance: Make sure you are connected to the correct database 
instance. In our case, it is ITSO. 

2. Enter the parameters in the Connect to Server dialog to connect to your database. Click 
the Options button at the Connect to Server window, and select ITSO as the value for 
Connect to the database. See Figure 8-9. 



Figure 8-9 Connect to database ITSO 

3. Insert the text of the script from Example 8-1 on page 398 into the script editor, and 
execute it by selecting Data Transact-SQL Editor Execute SQL. Verify the 
command output in the Messages tab to make sure that the table was created 
successfully. See Figure 8-10 on page 401. 
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-IF NOT EXISTS (SELECT * FROM sys . objects WHERE object_id = OB JECT_ID [N 1 [ dbo] . [ F ILE_STATUS] 1 ) ANT =9= 
E BEGIN] 

□ CREATE TABLE [dbo] . [ F ILE_STATUS] ( 

[id] [int] IDENTITY ( 1, 1 J NOT NULL, 

[file_name] [nvarchau] (64: COLLATE SQL_Lat inl_Gener al_CP 1_C I_AS NOT NULL, 

[parts_in_total] [int] NOT NULL, 

[pauts_puGcessed] [int] NOT NULL, 

[completed] [bit] NOT NULL, 

[record_time] [datetime] NOT NULL, 

[ last_modif ied] [datetime] NOT NULL, 

[ repor t_msg_id] [nchar] (51) COLLATE SQL_Lat inl_General_CPl_CI_AS NULL, 

CONSTRAINT [ PK_F ILE_STATUS] PRIMARY KEY CLUSTERED 

( 

[id] ASC “ 

) WITH ( PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = 

.) 

END 
GO 

□ IF NOT EXISTS (SELECT * FROM sys . indexes WHERE object_id = OBJECT_ID [N 1 [dbo] . [ F ILE_STATUS] 1 ) AND 
-CREATE UNIQUE NONCLUSTERED INDEX [ IX_F ILE_STATUS] ON [dbo] . [FILE_STATUS] 

( 

[ repor t_msg_id] ASC 

) WITH ( PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, S ORT_ IN_TE HP D B = OFF, IGNORE_DUP_KEY = 0! 
GO 

100 % - jJ 

1^ Messages 

Command(s) completed successfully 


100 % - j_ 

Figure 8-10 Script for FILE_STATUS table after executing 



8.3.2 Configuring the ODBC data source 

To use a database from Message Broker, you should create a System Data Source (DS) 
using Administrative tools managing snapshot. Use the following procedure to configure the 
ODBC data source. 

1 . Select Start -» Administrative Tools -» Data Sources (ODBC). 

2. Select the System DSN tab, and click Add. 

3. In the ODBC DataSource Administrator dialog, select SQL Server Native Client 10.0 as 
a database driver, and then click Finish. 

4. Enter FTE_DS as the name, provide a description, and select the server, as shown in 
Figure 8-1 1 on page 402. Click Next. 
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Figure 8-11 Creating new ODBC Data source 
5. Enter ITSO for SPN (optional), as shown in Figure 8-12. Click Next. 
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Figure 8- 12 Creating new ODBC Data source (continued) 


6. Click Next in the next two screens, and then click Finish to complete the ODBC DS 
creation process. 


8.3.3 Preparing the file system structure 

Create a C : \ ITSO folder on the root of your local file system for the purpose of creating 
transfers and testing main message flows. 
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Create the following subdirectories in the folder: 

► \agent_a_in: This is a folder for files to be polled by the ITSO_A FTE agent. 

► \agent_brk_out: This is where the broker agent BRKJTSO.ITSO puts received files before 
processing them through FTE Input node. 

► \agent_b_out: This folder is used by ITSO_B agent as a destination for transfers from the 
broker. 


8.4 Applications emulated in this scenario 

This section describes how the business applications listed in section 8.1, “Scenario 
overview” on page 392 are emulated from the technology perspective. You configure two FTE 
Server Agents and create two message flows to emulate Branch, Report Data Warehouse, 
and Volume Analysis System applications. You also create a simple .NET library to 
demonstrate how to call .NET directly from ESQL code. 


8.4.1 Branch application (FTE) 

This application emulator works outside of the WebSphere Message Broker environment. It is 
emulated by a stand-alone FTE server agent, as shown in Figure 8-13. 



Figure 8-13 Branch application emulator schema 


The branch application has no access to the broker; instead, it just produces files with reports 
and puts them into a Network-Attached Storage (NAS). The FTE application takes these files 
and forwards them to the another FTE agent that is embedded in the broker and runs under 
control of the execution group process. 

To emulate the Branch Application, we must put an appropriate file into a directory polled by 
the FTE agent. 

To create this agent, install the FTE server code binaries to the machine where it will run. For 
our scenario, we assume that the FTE agent will run on the same machine as the broker. 
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Note: The FTE server agent code binaries are shipped with WebSphere Message Broker, 
so you do not need to install them if you only plan to use FTE nodes inside the broker. This 
code is managed by the license of the WebSphere Message Broker. But, to run FTE as a 
stand-alone agent, install WebSphere MQ File Transfer Edition first. In this case, you need 
a separate license either for FTE client or for FTE server. 


Installing the FTE server agent 

It is beyond the scope of this chapter to provide the details for installation. Full installation 
details are provided in the Information Center and in following article at the IBM 
developerWorks® website: 

http://www.i bm.com/devel operworks/websphere/1 i brary/techarti cl es/1003_phi 1 1 i ps/100 
3_phillips.html 

Important note: Make sure the username under which you install and run the FTE 
configuration scripts is short enough to fit into the MQCHAR12 Userldenti fi er field of the 
MQMD structure. If your username is longer than 12 characters, you will have problems 
configuring and registering FTE agents. For example your agent will not appear under the 
configured agents list in the FTE Configuration Manager. 


This scenario uses the following names and settings during the installation: 

► Coordination Queue Manager name is QM_ITS0 

► FTE agent parameters: 

- Agent name is ITS0_A 

- Agent queue manager is QMJTSO 

► Command queue manager name is QMJTSO 

► Transport mode to connect to QMJTSO was selected to Bi ndi ngs 

Installation path defaults depend on the operating system. In our installation, the Product 
install folder was installed at: 

C:\Program Files (x86)\IBM\WMQFTE 

The Configuration folder was installed at: 

C : \ProgramData\IBM\WMQFTE\conf i g\ 

After installing WebSphere MQ FTE, you must run an MQSC script against the QMJTSO 
queue manager to create the resources required to run the FTE agent. The script you need to 
run is created during installation and is stored in the following path: 

C:\ProgramData\IBM\WMQFTE\config\QM_ITSO\agents\ITSO_A\ITSO_A_create.mqsc 

Use the following command to run the script: 
runmqsc QMJTSO < 

C:\ProgramData\IBM\WMQFTE\config\QM_ITSO\agents\ITSO_A\ITSO_A_create.mqsc 

If the command runs successfully, you can see the three lines in Example 8-2 at the end of 
the output. 

Example 8-2 Sample output of ITSO_A_create. mqsc script 

11 MQSC commands read. 

No commands have a syntax error. 
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All valid MQSC commands were processed. 


Installing the FTE plug-in for WebSphere MQ Explorer 

To monitor and submit your file transfers from a GUI application, you need to install binaries to 
augment the WebSphere MQ Explorer with FTE management components. You only need to 
install them at the machine where FTE coordination queue manager resides. 

The installation procedure for the FTE plug-in for WebSphere MQ Explorer is well explained in 
this developerWorks article: 

http://www. i bm.com/devel operworks/websphere/1 i brary/techarti cl es/1003_phi 1 1 i ps/100 
3_phi 1 1 i ps . html IN101B2 


Creating and configuring FTE agent ITSO_B 

Create a second FTE agent named ITS0_B as a destination for aggregated replies from 
Message Broker. The agent will use another MQ Queue manager named QM_FTE. This will 
demonstrate the concept of distributed FTE network. 


Note: In our scenario, we use a single MQ and FTE installation on one machine. But you 
can easily adopt the technique described in this section for the distributed FTE network. 
For example, you can use this technique if you need to connect a remote FTE Server agent 
with your FTE Configuration Manager. Just install the product binaries and replace 
1 ocal host within the scripts with the actual IP addresses. 


Set up a new queue manager and the communication channels between QM_FTE and 
QMJTSO. Use the following procedure: 

1 . Create the QM_FTE using the following command: 
crtmqm QM_FTE 

2. Start it using the following command: 
strmqm QM_FTE 

3. Connect to it using the runmqsc command processor: 
runmqsc QM_FTE 

4. Copy and paste the script in Example 8-3 to set up channels to and from the Configuration 
Queue Manager and to create an alias for the QMJTSO queue manager. 

Example 8-3 Configuring QM_FTE queue manager 

DEFINE LISTENER (LISTENER. TCP) TRPTYPE(TCP) P0RT(1415) CONTROL(QMGR) 

START LISTENER (LISTENER. TCP) 

DEFINE QREMOTE (QMJTSO) RQMNAME (QMJTSO) XMITQ(T0. QMJTSO) 

DEFINE QLOCAL (TO. QMJTSO) USAGE(XMITQ) TRIGGER + 

TRIGTYPE(FIRST) + 

TRIGDPTH(l) + 

TRIGMPRI (0) + 

TRIGDATA( 1 QMJTE. TO. QMJTSO ' ) + 

PROCESS (' ') + 

INITQC SYSTEM. CHANNEL. INITQ ' ) 

DEFINE CHANNEL (QMJTE. TO. QMJTSO) CHLTYPE (SDR) + 

CONNAME ( 1 1 ocal host (1414) 1 ) + 

XMITQ('T0. QMJTSO') 
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DEFINE CHANNEL (QM_ITSO.TO.QM_FTE) CHLTYPE (RCVR) 
START CHANNEL (QM_ITSO.TO.QM_FTE) 

END 


5. Connect to QMJTSO using the following command: 
runmqsc QM_ITS0 

6. Copy and paste the script from Example 8-4 to create corresponded objects at QMJTSO. 
Example 8-4 Configuring QMJTSO queue manager 


DEFINE QREMOTE (QMFTE) RQMNAME(QM_FTE) XMITQ(TO.QM_FTE) 
DEFINE QL0CAL(T0.QM_FTE) USAGE(XMITQ) TRIGGER + 

TRI GTYPE (FIRST) + 

TRIGDPTH ( 1) + 

TRIGMPRI (0) + 

TRIGDATA( 'QM_ITS0.T0.QM_FTE ' ) + 

PROCESS (' ') + 

INITQC 1 SYSTEM. CHANNEL. INITQ ' ) 

DEFINE CHANNEL (QMJTSO. TO. QM_FTE) CHLTYPE (SDR) + 
CONNAME ( 1 1 ocal host (1415) ') + 

XMITQ ( ' TO . QM_FTE 1 ) 

DEFINE CHANNEL (QM_FTE. TO. QMJTSO) CHLTYPE (RCVR) 

START CHANNEL (QMJTE. TO. QMJTSO) 

END 


As a result, you created two pairs of channels between the Queue Managers and other 
complimentary components to enable communication between Agent ITSOJ3 with the 
Configuration Manager and back. 

7. Configure an ITSO_B agent using the following command line: 

fteCreateAgent.cmd -agentName ITS0_B -agentQMgr QMJTE -f 

If the command completes successfully, you will see the line in Example 8-5 at the end of 
the output. 

Example 8-5 Configuring ITSO_B agent 

BFGCL0053I: Agent configured and registered successfully. 


This means that ITSOJ3 agent successfully updated (registered) the Configuration 
Manager’s information, and it now appears in the list of available agents, as shown in 
Figure 8-14. 


• ® MQ Explorer - Navigator £3" = 

°1 

0 MQ Explorer - Content £3 

i 3 


Agents 
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& Queue Manager Clusters 
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-] Ci^i Managed File Transfer 
- (3 QMJTSO 

. am "r-rff 

SbhSM* 

^ Monitors 
lip Transfer Templates 
iip Transfer Log 
IS Pending Transfers 

±J 


Name | Description | Status | I 

BRKJTSO.ITSO No information 1 

ITSO_A Unreachable ; 

ITSO_B Stopped 1 

Filter the displayed status entries: 

F~ 


Y Administration Log £3 ^p Managed File Transfer - ( 


Figure 8-14 List of the registered agents 


406 Using WebSphere Message Broker V8 in Mid-Market Environments 


8. To complete the ITSO_B configuration, execute a configuration script against QM_FTE 
manager: 

runmqsc QM_ITS0 < 

C:\ProgramData\IBM\WMQFTE\config\QM_ITSO\agents\ITSO_B\ITSO_B_create.mqsc 

9. Start both agents using the following command lines: 

fteStartAgent.cmd ITS0_A 
fteStartAgent.cmd ITS0_B 

10. Verify that both agents started by using MQ Explorer. The result is similar to Figure 8-15. 


§ja- MQ Explorer - Navigator £3 



15? Authentication ] | 

C5 Queue Manager Clusters 
(5 JM5 Administered Objects 
Cfr Managed File Transfer 
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MQ Explorer - Content 


Agents 


Name 


Description | Status 


Source transfer 


Destination transfer 


BRKJTSO.ITSO 
IT50_A 
IT50 B 


No information 0 

Active 1 

Ready 0 


Filter the displayed status entries: 


Figure 8-15 FTE agents status 


FTE agent status: Ready status of the FTE agent means it is started. Active status means 
that the agent is ready and is processing a transfer. 


Setting up a file transfer 

To set up a file transfer: 

1 . Open WebSphere MQ Explorer by clicking Start ->• All Programs -» IBM WebSphere 
MQ -» WebSphere MQ Explorer. 

2. In the MQ Explorer-Navigator view, navigate to Managed File Transfer -» QMJTSO -» 
Transfer Templates. 

3. Right-click this element, and select New Transfer. In the new dialog, enter the 
parameters, as shown in Figure 8-16 on page 408. Click Next. 
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Figure 8-16 Creating a file transfer 

4. In the new dialog, set up a schedule for this transfer for it to occur every minute and 
forever, as shown in Figure 8-17 on page 409. 
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*§» Create New Managed File Transfer 
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Enter schedule and event settings. 
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< Back 


Next > 


Finish 


Cancel 


Figure 8-17 Scheduling file transfer 


5. Set the start time to a time in the past (for example, an hour) to ensure that transfers start 
immediately after creation. Click Finish to create a file transfer. 

6. Verify that the transfer created successfully by navigating to Managed File Transfer -» 
QMJTSO -> Transfer Templates. 


8.4.2 Report Data Warehouse 

The Report Data Warehouse (RDW) application is MQ-enabled. This means that this 
application can receive WebSphere MQ messages, process them, and send a reply back to 
WebSphere MQ directly without using any adaptors, as shown in Figure 8-18. 



Figure 8-18 RDW application schema 

Thus, it can be easily emulated as a message flow within the broker. 


Chapter 8. Integrating file transfer with WebSphere MQ FTE into the message flow 409 




The emulator for an RDW application is straightforward. It consists only of two nodes: MQ 
Input and MQ Reply, as shown in Figure 8-19. 



MQ Input MQ Reply 


Figure 8-19 Report Data Warehouse Emulator 

In our scenario, this RDW emulator technically does not do anything else than sending back 
an original request without any modification. 

MQReply node behavior: The default setting for the MQReply node is to copy Msgld from 
the original message into Correlationld MQMD field and send a message to the queue that 
is specified in the ReplyToQ field of the message. Although you can change this behavior 
to a different correlation schema, consider that Aggregate nodes use this particular default 
algorithm to correlate requests with replies. 

Creating a new flow 

To create a new flow: 

1 . In the Message Broker Toolkit, select File — > New -» Application. 

2. Enter ReportsAppl i cation as the application name, as shown in Figure 8-20. Click 

Finish. 



Figure 8-20 Creating the ReportsApplication 

3. Right-click under the new application, and select New ->• Message Flow to create a 
message flow with the same name. 

4. In the new dialog, enter ReportsAppl i cati on as the message flow name, as shown in 
Figure 8-21 on page 41 1 . Click Finish. 
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Figure 8-21 Creating ReportApplication flow 

5. Drag-and-drop the MQInput and MQReply nodes from the Palette to the canvas. Connect 
the out terminal of the MQInput node to the input terminal of the MQReply node, as shown 
in Figure 8-22. 
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Figure 8-22 Composing ReportApplication flow 


6. Select the MQ Input node and, in the Properties view, enter REPT.OUT as the queue name, 
as shown in Figure 8-23 on page 412. 
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Figure 8-23 Setting Basic properties of MQ Input Node 


7. Switch to the Input Message Parsing tab of the same window, and select XMLNSC as the 
message domain, as shown in Figure 8-24. 


Properties £3 * Problems | H Deployment Log 

J^j MQ Input Node Properties - MQ Input 
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Figure 8-24 Setting Input Message Parsing properties of MQ Input Node 


Note: The XML message format used here does not require a specific message model 
definition because it is a self-describing message format. But, the main FTE scenario uses 
a special tagged-delimited message, so it does include a DFDL message model, which we 
describe later in Section 8.5.3, “Creating a message definition” on page 422. 


8. Click File Save from the main menu. The RDW emulator is now complete. Before it can 
be used in runtime, it must be deployed and MQ queue resources created for it. 

Configuring WebSphere MQ for the RDW application emulator 

To create an input queue for the RDW emulator: 

1 . In WebSphere MQ Explorer, select Queues in the path under Queue Manager. Right-click 
Queues, and select New ->• Local Queue, as shown in Figure 8-25 on page 413. 
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Figure 8-25 Create new local WebSphere MO Queue 


2. In the new dialog, enter REPT.OUT as the queue name, and click Finish. The REPT.OUT 
queue appears in the list of queues of the BRKJTSO manager, as shown in Figure 8-26. 
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Figure 8-26 New REPT.OUT queue 


Note: The reply queue for this message flow is created during set up of the main flow of 
this scenario. 


Deploying the RDW application emulator 

To deploy the RDW application emulator: 

1 . In the Application Development view, right-click ReportsApplication, and select Deploy. 

2. In the new dialog, select MOCKS from the path shown in Figure 8-27 on page 414. Click 

Finish. 
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Figure 8-27 

3. Ensure that the flow deployed without errors and appears in the list of flows within the 
execution group MOCKS. If the flow does not appear, check the Deployment log view for 
the errors. 


Finish 


Cancel 


8.4.3 Volume Analysis System 

The Volume Analysis System (VAS) business application is technically a .NET application, 
which is remotely accessible through Windows Common Framework (WCF). The .NET client 
part of the VAS application is a library that is executed within the Broker’s owned .NET 
runtime. See Figure 8-28. 



Figure 8-28 VAS application scheme 


Accessing .NET code from ESQL 

There are two different styles of using of .NET code from message flows. The first is to use a 
.NETCompute node, and the second is to invoke .NET procedures from an ESQL Compute 
node using a CREATE PROCEDURE statement. 
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Using a .NETCompute node for work with .NET in message flow has the following 
advantages: 

► It can create instances of the classes and pass parameters of complex types to their 
methods. 

► It can be used as a client for calling remote .NET application through WCF. 

► It can be used for invoking non-static methods. 

► It is more familiar to .NET programmers. 

Using .NET from ESQL compute node has its own advantages: 

► You can combine in one node ESQL to manipulate the data from messages and database 
tables and, at the same time, use the .NET API to access .NET and WCF applications. 

► It is easier to manipulate and browse complex message data from ESQL. 

► You do not have to create new Microsoft Visual Studio 2010 projects as long as you only 
need to call existing public static methods from .NET assembly. 

► It is more familiar to broker developers. 

Chapter 7, “Scenario: Integrating Windows Communication Foundation in message flows - 
Part 2” on page 273 is dedicated to a discussion about integration of WebSphere Message 
Broker with WCF applications. It calls .NET code from a .NETCompute node. In our scenario, 
we demonstrate how to invoke .NET code directly from ESQL. 

The technical details about how to invoke .NET directly from the ESQL and the advantages of 
this approach are discussed in “Creating the broker for the VAS application emulator” on 
page 416. 

Creating the VAS application .NET client emulator 

To create a VAS application .NET client emulator: 

1 . Start Visual Studio, and click File New Project. 

2. Select Visual C# from the left side of the window, and select Class Library as the project 
template. Perform the following steps: 

a. Enter Operati onsAppCl i ent as the name. 

b. Enter c:\ITS0 as the Location. 

c. Enter Operati onsAppCl i ent as the solution name. 

Click OK. 

3. In the Solutions Explorer, right-click the Cl assl.cs file, and select Rename. Rename that 
class to Operati onsAppCl i ent . cs. 

4. Open the Operati onsAppCl i ent . cs, and replace the generated code with the code in 
Example 8-6. 

Example 8-6 Content of OperationsAppClient.es class 


using System; 

namespace Operati onsAppCl i ent 
{ 

public class Operati onsAppCl i ent 
{ 

public static string registerOperati on (string branchld, string transactionld, 
string symbol, double price, int amount, double commissi onl, double commission2) 

{ 

return "00000000-0000-0000-0000-00000" + amount + "0" + transactionld; 
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} 


In this sample method, we return nothing more than a string of numbers formatted as GUID, 
for example, {00000000-0000-0000-0000-000012345678}. 

5. Press Ctrl+S to save the file. 

6. Click Build Build the solution from the main menu. The text in Example 8-7 is 
displayed in the Output view. 

Example 8-7 Building the OperationsAppClient.es file 


Build started: Project: OperationsAppCl ient, Configuration: Debug Any CPU 

Operati onsAppCl i ent -> 

c : \ITS0\0perati onsAppCl i ent\Operati onsAppCl i ent\bi n\Debug\0perati onsAppCl i ent .dll 

========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ========== 


Limited functionality: The OperationsAppCIient here is used as only an emulator of the 
real application. Because the main purpose of this scenario is to demonstrate the 
technique of calling .NET from ESQL, we are neither going into the details of 
communications between the .NET client and server nor creating a full fledged WCF client. 


7. Close Visual Studio, and switch back to the Message Broker Toolkit. 

Creating the broker for the VAS application emulator 

The Aggregate nodes used in the scenario are designed to work with WebSphere MQ 
messages (see 8.5.5, “Using aggregation in WebSphere Message Broker” on page 431 for 
more information). To use a broker-supplied aggregation mechanism, you must wrap a 
synchronous .NET call into an asynchronous MQ invocation and put it into separate a 
message flow. In this scenario, we use the OperationsApplicationClient flow. 

To develop the message flow for the VAS application emulator: 

1 . Create a new application and message flow, both named Operati onsAppl i cati onCl i ent. 
See Figure 8-29. 



Figure 8-29 Create a new application and message flow 

2. From the palette, perform the following steps: 

a. Drag-and-drop the MQ Input and MQ Reply nodes on to the canvas. 

b. Drag-and-drop a Compute node from the Transformation tab of the palette to the 
canvas. Rename the Compute node WCF Cl ient. 
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c. Wire the three nodes, as shown in Figure 8-30. 
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Figure 8-30 Creating a WAS application emulator 


3. Select the MQ Input node and enter the following parameters in the Properties view: 

a. In the Basic tab, enter OPTN.OUT as the queue name. 

b. In the Input Message Parsing tab, select XMLNSC : For XML messages (namespace 
aware, validation, low memory use) as the message domain. 

c. Press Ctrl+S to save your changes. 
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Figure 8-31 MQ Input node properties for VAS emulator 

4. Select the WCF Client node. In the Basic tab of the Properties view, select 

OperationsApplication_WCF_Client as the value for ESQL Module. 

5. Click Ctrl+S to save your changes. 

6. Double-click the WCF Client node. In the ESQL window, copy and paste the declaration in 
Example 8-8 on the next line after the CREATE COMPUTE MODULE statement. 

Example 8-8 Declaring the .NET procedure inside the ESQL module 


CREATE PROCEDURE WCF_ProcessOperat i on ( 

IN branchld CHARACTER, 

IN transactionld CHARACTER, 

IN symbol CHARACTER, 

IN price FLOAT NOT NULL, 

IN amount INT NOT NULL, 

IN commi ssionl FLOAT NOT NULL, 

IN commi ssion2 FLOAT NOT NULL) 

RETURNS CHARACTER 
LANGUAGE .NET 

EXTERNAL NAME "Operati onsAppCl ient.OperationsAppCl ient.regi sterOperati on" 
ASSEMBLY 

"c:\ITSO\OperationsAppCl ient\Operati onsAppCl ient\bin\Debug\OperationsAppCl ient.dl 1 
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Declare .NET procedure using drag-and-drop: The Message Broker Toolkit provides a 
plug-in that dramatically simplifies a process of declaring .NET methods inside ESQL 
modules. All you need to do to use this plug-in is to drag-and-drop the .NET library .dll 
file in to the ESQL compute module. As a result, a window where you can select a desired 
method to call from ESQL is displayed. The plug-in will generate an ESQL declaration. 


Select the .NET assembly class methods this Compute node will invoke 


! 0 © registerOperation 


Operations AppClient . Operations AppClient 


OK 


Cancel 


7. Replace the Function Main content block with the code shown in Example 8-9. 

Example 8-9 Calling .NET procedure from the ESQL module 

CREATE FUNCTION Main() RETURNS BOOLEAN 

BEGIN 

CALL CopyEnti reMessage() ; 

Declare b reference to OutputRoot.XMLNSC. branch; 

Declare op reference to b. operation; 

Set op. result = WCF_ProcessOperation( 

b.branch_number, op. transactions, op. symbol, 

CAST(op. price as FLOAT), 

CAST (op. amount as INT), 

CAST(op.commissionl as FLOAT), 

CAST(op.commission2 as FLOAT)); 

RETURN TRUE; 

END; 


8. Save and close the file. 


8.5 Creating the main message flow 

In this section, we create the primary message flow for the scenario. We illustrate integration 
with WebSphere MQ File Transfer Edition. We also show a process of modelling messages 
using the DFDL editor, (new in Message Broker V8.0). We guide you through creating fan-out 
and fan-in flows, which are common tasks, for example, when you integrate one front-end 
application with several back-end systems. 
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For those .NET developers who are interested in learning WebSphere Message Broker 
techniques, we also show a method of splitting a message into pieces and routing these 
different pieces to different end-systems using ESQL. 

Following the Design ->• Build -» Deploy -» Test paradigm, we start our main development 
from the design of a message flow and our data model, then we fill our message flow with 
code, build it, and then run an overall test through it. We also discuss possible extension 
points to this scenario. 


8.5.1 Message flow overview 

Figure 8-32 shows the completed message flow. This flow actually consists of two flows: the 
first processes a message from FTE Agent ITS0_A and sends an asynchronous request to 
subsequent systems and the second processes an asynchronous response from these 
systems and routes a combined message to the FTE Agent ITS0_B. 



The following list describes the behavior of each node: 

1 . The FTE Input node receives files from the FTE network and parses them into a logical 
tree. 

2. The Log File Status node writes general information about the received file into the 
database. 

3. The Aggregate Control node marks the beginning of the fan-out flow part. 

4. The Route node splits the message into report and operation parts and routes them to the 
RDW and VAS applications. 

5. The Reports node sends the message to the destination MQ queue for the RDW 
application. 

6. The Store Msgld node stores the generated messageld into the database. 

7. The Aggregate Request Reports node marks the completion of the request part of the 
Fan-out flow. 

8. The Operations node sends the message to the destination MQ queue for the VAS 
application. 
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9. The Aggregate Request Operations node marks the completion of the second request 
part of the fan-out flow. 

10. The Operations Reply node receives replies from the VAS application and parses them 
into a logical tree. 

1 1 .The Update Ops Status node records that replies were received from the VAS application. 

12. The Aggregate Reply node combines the replies and sends them as one message to the 
subsequent part of Fan-in flow. 

13. The Reports Reply node receives replies from the RDW application and parses them into 
the logical tree. 

14. The Update Reps Status node records that replies were received from the RDW 
application. 

15. The Complete File Status node updates the database with the completion status for the 
processed file and updates the last_modified information. 

16. The Combine Results node extracts information from the OPERATION and REPORT 
folders of the combined replies and creates a new message using the FTERecordSample 
DFDL data format definition. 

17. The FTE Output node sends files back to the WebSphere MQ File Transfer Edition. 


8.5.2 Creating and connecting the nodes 

The first step in building the message flow is to add and wire the nodes together: 

1. Create a new application named FTESample with an associated message flow named 
FTESampleFlow. 

2. Add the nodes in Table 8-1 and wire them together to form the flow. As you build the 
message flow, use Figure 8-32 on page 419 as a reference. 


Table 8-1 Node naming and wiring information 


Palette drawer / 
node type 

Node name and description 

Wiring information (terminal to node) 

File 

FTEInput 

FTE Input 

► Out: Log file status 

Database 

Database 

Log File Status 

► Out: Aggregate Control 

Routing 

AggregateControl 

Aggregate Control 

► Out: Route 

Transformation 

Compute 

Route 

► Out: Reports 

► Outl : Operations 

WebSphere MQ 

MQOutput 

Reports 

► Out: Store Msgld 

Database 

Database 

Store Msgld 

► Out: Aggregate Request Reports 

Routing 

AggregateRequest 

Aggregate Request Reports 

(none, end of flow) 

WebSphere MQ 

MQOutput 

Operations 

► Out: Aggregate Request Operations 
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Palette drawer / 
node type 

Node name and description 

Wiring information (terminal to node) 

Routing 

AggregateRequest 

Aggregate Request Operations 

(none, end of flow) 

WebSphere MQ 

MQInput 

Operations Reply 

► Out: Update Ops Status 

Database 

Database 

Update Ops Status 

► Out: Aggregate Reply 

Routing 

AggregateReply 

Aggregate Reply 

► Out: Complete File Status 

WebSphere MQ 

MQInput 

Reports Reply 

► Out: Update Reps Status 

Database 

Database 

Update Reps Status 

► Out: Aggregate Reply 

Database 

Database 

Complete File Status 

► Out: Combine Results 

Transformation 

Compute 

Combine Results 

► Out: FTE Output (In) 

File 

FTEOutput 

FTE Output 

(none, end of flow) 


3. Table 8-2 describes the configuration information for the node properties. Select each 
node in the canvas and enter or select the values for each of the properties. When you are 
finished, save the message flow. 


Table 8-2 Node properties 


Node 

Tabs, Fields, and Values 

FTEInput 

Do not configure this node yet. We configure this node later in 
“Configuring the FTE Input node for the scenario” on page 430, 
because we need to create a message definition first. 

Log File Status 

Basic: 

► Data Source: FTE_DS 

► Statement: FTESampl eFl ow_Log_Fi 1 e_Status 

Aggregate Control 

Basic: 

► Aggregate Name: FTE_AGGR 

Route 

Basic: 

► ESQL module: FTESampl eFl ow_Route 

Reports 

Basic: 

► Queue name: REPT.OUT 

Store Msgld 

Basic: 

► Data source: FTE_DS 

► Statement: FTESampl eFl ow_Store_Msg Id 

Aggregate Request 

Basic: 

Reports 

► Folder name: REPORT 
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Node 

Tabs, Fields, and Values 

Operations 

Basic: 

► Queue name: OPTN.OUT 

Aggregate Request 

Basic: 

Operations 

► Folder name: OPERATION 

Operations Reply 

Basic: 

► Queue name: OPTN.IN 

Input Message Parsing: 

► Message domain: XMLNSC 

Update Ops Status 

Basic: 

► Data source: FTE_DS 

► Statement: FTESampl eFl ow_Update_Ops_Status 

Aggregate Reply 

Basic: 

► Aggregate name: FTE_AGGR 

Reports Reply 

Basic: 

► Queue name: REPT.IN 

Input Message Parsing: 

► Message domain:DFDL 

► Message: {} : FTERecordSample 

Update Reps Status 

Basic: 

► Data source: FTE_DS 

► Statement: FTESampl eFl ow_Update_Reps_Status 

Complete File Status 

Basic: 

► Data source: FTE_DS 

► Statement: FTESampl eFl ow_Compl ete_Fi le_Status 

Combine Results 

Basic: 

► Data source: FTE_DS 

► ESQL module: FTESampl eFl ow_Combi ne_Resul ts 

► Compute mode: Local Envi ronment and Message 

FTE Output 

Do not configure this node yet. We configure this node later on in 
“Configuring the FTE Output node” on page 430, because we need 
to create a message definition first. 


Configuration is not complete yet: We configure the FTE nodes later in section 8.5.4, 
“Using FTE nodes” on page 429, because we need to create a message definition first. 

The code for the database and ESQL nodes is also provided in the following sections. See 
8.5.7, “Accessing databases from the database nodes” on page 435 and 8.5.6, “Producing 
multiple messages from the compute node” on page 434 


8.5.3 Creating a message definition 

In this section, we use the Message Broker Toolkit to create a DFDL message definition to 
parse a report file inside the FTESampleFlow message flow. 

1 . Right-click the FTESample application, and select New -» Message Model. 
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2. Select Record Oriented Text, and click Next. 

3. On the next screen, select Create an empty DFDL schema file, I will model my data 
using the DFDL schema editor, and click Next. 

4. Enter FTERecordSampl e as the DFDL schema file name. Click Finish. 

5. In the schema that displays, select the Add a message to the schema icon. In the Add 
Message dialog, enter FTERecordSampl e as the message name, as shown in Figure 8-33. 
click OK. 



Figure 8-33 Add a new message to the schema 


6. Right-click the sequence element, and select Add Complex Local Element, as shown in 
Figure 8-34 on page 424. 
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Name Type Min Occurs Max Occurs Default Value Sample Value 


□ [!_, FTERecordSample 

0j did sequence 
Add a Local Element 

1 i i 

<^Undo 
■■:[> Redo 
Revert 

Move to a New Model Group. . . 
^lj- Move Up 
Move Down 


Add a Local Element 

Add Complex Local Element. . . 1 

Add Sequence 
■f* Add Choice 

rjjpj Add Element Reference. . . 
iCl Add Group Reference. . . 

© Add Hidden Group Reference... (not supported in current IBM DFDL implementation) 

it... Test Parse Model 
i i Test Serialize Model 
[U Create a Logical Instance From Model 

Delete 

Show In 

► 


Figure 8-34 Adding a complex local element 


7. In the Add Complex Local Element dialog, enter branch as the Name, and choose 
sequence as the Composite Type. Click OK. 

The new element is added to the sequence, as shown in Figure 8-35. 



Figure 8-35 Adding a new branch element 

8. Repeat steps 6 and 7 for the same global sequence under FTERecordSample, and 
create additional child elements named: 

- customer 

- operations 

- report 

9. Right-click sequence under the branch element, and select Create Local Element. Enter 
branch_number as its name. Leave the Type of this element as string. 

10. Repeat step 9 to create the date element under branch (see Figure 8-36 on page 425). 

1 1 .Using step 9 as an example, create a child element named i d under customer. 

12. Create a complex child element named operation under operations sequence (see 
Figure 8-36 on page 425). 

13. Populate the operation sequence with child elements, as shown on Figure 8-36 on 
page 425. You can leave the type of elements as string for now. We will explain how to 
change them later. 


424 Using WebSphere Message Broker V8 in Mid-Market Environments 




14. Using Figure 8-36 as an example, create the remaining complex elements and their 
respective child elements. 


Name 

Type 

Min Occurs 

Max Occurs 

Default Value 

Sample Value 

□ [¥] FTERecord5ample 

□ nou sequence 


1 

1 



B [e] branch 


1 

1 



□ □□□ sequence 


1 

1 



[§] branchjiumber 

string 

1 

1 

1 

1 

[fj date 

string 

1 

1 

1.3.2012 

1.3.2012 

B [ej customer 


1 

1 



B sequence 


1 

1 



Hj id 

string 

1 

1 

R90306 

R90306 

B [ej operations 


0 

1 



B sequence 


1 

1 



B [|j operation 


1 

unbounded 



B sequence 


1 

1 



[¥] transactions 

string 

1 

1 

1026 

1026 

[¥] symbol 

string 

1 

1 

IBM 

IBM 

[I] price 

double 

1 

1 

190.1 

190.1 

[¥] amount 

int 

1 

1 

10 

10 

[¥] commission 1 

double 

1 

1 

0.1 

0.1 

[¥] commissionZ 

double 

1 

1 

0.01 

O.Ol 

[¥] registeredID 

string 

0 

1 



B [ej report 


0 

1 



B »»» sequence 


1 

1 



B 0 stocks 


1 

1 



B □a- sequence 


1 

1 



B [¥] stock 


1 

unbounded 



B sequence 


1 

1 



[ej name 

string 

1 

1 

IBM 

IBM 

[ej open_amount 

double 

1 

1 

0 

0 

[gj dose_amount 

double 

1 

1 

10 

10 

[ej delta 

double 

1 

1 

0 

0 

B [jjj total_commission 


1 

1 



B sequence 


1 

1 



[¥] commission 1 

double 

1 

1 

1.2 

1.2 

[¥] commissionZ 

double 

1 

1 

0.01 

0.01 

[¥] total 

double 

1 

1 

1.21 

1.21 

B [1j cash 


1 

1 



B □■»«. sequence 


1 

1 



[¥] open_amount 

double 

1 

1 

1000000 

1000000 

[¥] dose_amount 

double 

1 

1 

500000 

500000 

[f] delta 

double 

1 

1 

-500000 

-500000 


Figure 8-36 FTERecordSample data format definition 


1 5. For each element of Type doubt e in Figure 8-36: 

a. Click the respective cell under the Type column, and select double from the drop-down 
menu. 

b. Select the element, and in the Representation Properties panel on the right side of the 
editor window, find the Text Connect properties section. 

c. Click to expand Text Number Representation, and enter #####.## as a value for 
Number Pattern property, as shown in Figure 8-37 on page 426. 


Chapter 8. Integrating file transfer with WebSphere MQ FTE into the message flow 425 


□ Text Content 



- Text Number Represented 

^ standard 


Number Pattern 

#####.## 



Grouping Separator 

i?. j 



Decimal Separator 

R- 



Escape Scheme Reference 

M recSeoFieldsFmt : RecordEscaoe 




Figure 8-37 Number format properties for element of type double 

16. Select the Type i nt for the amount element under the operation sequence. 

17. Select the operations element: 

a. In the Occurrences section in the Representation Properties at the right side of the 
editor window, set Occurs Count Kind to the impl i ci t value. 

b. Set the Min occurs property, and enter 0 as the value. 

18. Repeat step 17 for the registeredID element under the operation sequence. 

19. Repeat step 17 for the report element. 

20. Select the unbounded value for the Max occurs column for the operation and stock 
elements. 

21 .(Optional). Change the default and sample values of each element to the values shown in 
Figure 8-36 on page 425. 

22. Select the sequence element directly under the FTERecordSample element. In the 
Delimiters section in the Representation Properties panel, change the values of the 
properties Separator, Initiator, Terminator to <no separator^ <no initiators <no 
termi nator> respectively by clearing the values of these fields. 

23. Using step 22 as an example, change the Separator, Initiator and Terminator properties for 
each element, as shown in Table 8-3. 


Note: There should be no spaces and new lines in the values for the Separator, Initiator 
and Terminator properties. Any new line and space that you see in Table 8-3 is present 
only because of limitations of the page size. 


Table 8-3 Delimiters for the FTERecordSample format 


Relative path 

Element 

Separator 

Initiator 

Terminator 

/ 

sequence 

<no separator 

<no initiator 

<no terminator> 

/ 

branch 


BRANCH%WSP*; 

%CR;%LF; 

/branch 

sequence 

, 

<no initiator 

<no terminator> 

/branch 

branch_number 


%WSP*;# 

<no terminator> 

/branch 

date 


%S P ; D ATE%S P; 

<no terminator> 

/ 

customer 


CUSTOMER 

%CR;%LF; 

/customer 

sequence 

, 

<no initiator 

<no terminator> 

/customer 

id 


%SP;ID:%SP; 

<no terminator> 
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/ 


operations 


OPERA- 

TIONS%CR;%LF; 


%C R ; %L F; E N D%S P ; O F%S P ; O 
PERATIONS%CR;%LF; 




/operations 

sequence 

/operations 

operation 

operations/oper- 

ation 

sequence 

operations/oper- 

ation 

transactionID 

operations/oper- 

ation 

symbol 

operations/oper- 

ation 

price 

operations/oper- 

ation 

amount 

operations/oper- 

ation 

commissionl 

operations/oper- 

ation 

commission2 

operations/oper- 

ation 

registered ID 

/ 

report 

report 

/sequence 

report 

/stocks 

report/stocks 

sequence 

report/stocks 

stock 

report/stocks/sto 

ck 

sequence 

report/stocks/sto 

ck 

name 

report/stocks/sto 

ck 

open_amount 

report/stocks/sto 

ck 

close_amount 





<no initiator 

<no terminator> 

%SP; 

<no terminator> 

<no initiator 

<no terminator> 

<no initiator 

<no terminator> 

%SP; 

<no terminator> 

%SP; 

<no terminator> 

%SP; 

<no terminator> 

%SP; 

<no terminator> 

%SP; 

<no terminator> 

%SP; 

<no terminator> 

REPORT%CR;%LF; 

<no terminator> 

<no initiator 

<no terminator> 

ST OCKS%C R ; %LF; 

%C R ; %L F ; E N D%S P ; 0 F%S P ; S 
T OC KS%C R ; %L F; 

<no initiator 

<no terminator> 

%SP; 

<no terminator> 

<no initiator 

<no terminator> 

<no initiator 

<no terminator> 

%SP; 

<no terminator> 

%SP; 

<no terminator> 
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report/stocks/sto 

ck 

delta 


%SP; 

<no terminator> 

report 

total_commission 


COMMIS- 

SION%CR;%LF; 

%CR;%LF; 

report/total_com 

mission 

sequence 

- 

<no initiator 

<no terminator> 

report/total_com 

mission 

comissionl 


%SP; 

<no terminator> 

report/total_com 

mission 

comission2 


%SP; 

<no terminator> 

report/total_com 

mission 

total 


%SP; 


report 

cash 


CAS H %C R ; % L F ; 

%CR;%LF; 

report/cash 

sequence 

, 

<no initiator 

<no terminator> 

report/cash 

open_amount 


%SP; 


report/cash 

close_amount 


%SP; 


report/cash 

delta 


%SP; 



Special characters: Because DFDL is an extension of WSDL, it uses an XML-like style for 
defining non-printable or special characters. You can find some of these characters in 
Table 8-3 on page 426. %SP stands for space character, %WSP stands for any whitespace 
character, %CR is carriage return and %LF is line feed. You can also use %WSP*, which 
means optional whitespace or %WSP+, which means one or more whitespaces. 


24. Save your work. You will verify that the message format definition is correct in the next 
sections. 

Sample file used in scenario 

We used the text file in Example 8-10 to verify that the scenario is working. 

Example 8-10 Content of the branch_file. txt 

BRANCH #1, DATE 1.3.2012 
CUSTOMER ID: R90306 
OPERATIONS 


1917, 

IBM, 

190. 

.10, 

20, 

0 . 

.38, 

0, 

.03 

1945, 

IBM, 

190. 

.50, 

20, 

0 . 

.38, 

0, 

.03 

1976, 

IBM, 

190. 

.99, 

10, 

0 . 

.38, 

0, 

.03 


END OF OPERATIONS 

REPORT 

STOCKS 

IBM, 100, 150, 50 
END OF STOCKS 
COMMISSION 
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1.14, 0.09, 1.23 
CASH 

1000000, 990476.87, -9523.13 


You can verify that your definition of the FTESampleRecord message is correct by executing 

a test parsing of that message. 

Test parsing the DFDL model 

To test parse the DFDL model: 

1 . Create a new text file named branch_fi 1 e.txt. Copy and paste the content of 
Example 8-10 on page 428 to this file, and store it in the c:\ITS0 folder of the file system. 

Note: branch_fi 1 e.txt should have an empty last line and empty space in front of each 
operation, stock, and commission elements, as defined in the FTESampleRecord 
format and shown in Example 8-10 on page 428. 

2. Click the Test Parse Model icon on the top-left corner of the main DFDL editor window in 
the Message Broker Toolkit. Select FTERecordSample as a Message Name, and browse 
for the branch_file.txt using the Content from a data file option. 

3. Click OK, and then switch to the DFDL Test perspective in the Message Broker Toolkit. 
After a while, you should see a hint stating ‘Parsing completed successfully’. If it is not, 
you should go back and check the message elements properties with Table 8-3 on 
page 426. 


8.5.4 Using FTE nodes 

The broker interacts with the FTE network by means of the FTEInput and FTEOutput node 
types. These nodes read and write files from and to the FTE network, respectively. FTE 
nodes can parse records in the file and have the ability to process large files without reading 
the entire contents into memory at the same time. To configure FTE nodes, specify a file 
mask for incoming files and the remote FTE agent parameters for outgoing files. You do not 
have to create the agent that handles the incoming files because the broker handles this 
automatically. 

FTE Input node overview 

The FTEInput node receives files from remote FTE agents. On deploy, the broker 
automatically creates an FTE agent and its underlying queues, creating one agent per each 
execution group that contains a message flow with FTEInput nodes. The FTE agent name is 
derived from Broker. ExecutionGroup and is not configurable. The name must be a valid 
format for generating the queue name. In our scenario, the name of the FTE agent that the 
broker will generate is BRK_ITS0. ITS0. 

The FTE Input node does not use a polling mechanism to scan directories because it is 
triggered by the embedded agent when a file arrives and the transfer is complete. It 
processes each file in a transfer separately and can process each file in parallel. 

In addition to receiving the data from the transfer, it also receives all the metadata associated 
with the transfer. This includes information from FTE, but can also include user-defined data. 

Each FTE Input node can specify a filter of which files it wants to process. By default, it 
processes all files. If two nodes both have a filter that matches a file, only one will get it. By 
default, if no filter expression is given, the node accepts any transferred file. 
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The file name filter accepts wild cards, blank (accept any files) or a string that must match 
exactly. Relative paths are allowed and are relative to the default transfer directory. 

Configuring the FTE Input node for the scenario 

To configure the FTEInput node: 

1 . Select the FTEInput node on the canvas to open the Properties view. 

2. Select DFDL as the message domain in the Input Message Parsing tab, and choose 
FTERecordSample as the message, as shown in Figure 8-38. 


d Properties £2 \ [" Problems |_B Deployment Log 


|]f j FTE Input Node Properties - FTE Input 


Description 

Determine how the node parses incoming messages. 

Basic 

Message domain DFDL : For binary or text messages with a Data Format Description Language schema model 

Input Message Parsing 

Parser Options 

Message model | <DFDL schema files in Applications and Libraries > 

Retry 

Message | -()-:FTERecord5ample 

Records and Elements 

To open the DFDL schema file for the selected messaae, click here. . . 

Validation 

Transactions 

Physical format 

Instances 

Message coded character set ID* | Broker System Default 

Monitoring 

Message encoding* Broker System Determined 


Figure 8-38 Setting FTEInput node properties 


3. Select the Record and Elements tab, and select Parsed Record Sequence as the 

record detection mechanism. 

4. Select the Transactions tab, and select YES as the transaction mode value. This action 
allows all requests for the RDS and VAS applications to be committed to WebSphere MQ 
under a single unit of work. 

5. Click Ctrl+S to save your changes. 

FTE Output node overview 

The main properties of the FTEOutput node are the details of where to transfer the files. The 
properties can be overridden using the local environment. The destination the file is to be 
written to is a file system on a remote agent. The node first writes it to a staging directory on 
the local file system and then sends a request to the embedded agent to transfer it. 

Files are built up in a mqsi transmit directory before being moved to the final file name after 
the file is complete and the transfer request is sent to the FTE agent. The name in the staging 
area is the same as the name the file will be transferred to, unless a file with that name 
already exists on the local file system. If it exists, a number is appended to the file. The file 
name transferred to the remote system is not affected by this and will not have the number 
appended. 

Configuring the FTE Output node 

The only mandatory property you have to specify for the FTEOutput node is the destination 
file name in the Basic tab. 

Enter *.txt as the value, as shown in Figure 8-39 on page 431 . This value is just a stub for 
the required field. The name is set later using ESQL. 
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Properties £3 

rf VD n 

i&B FTE Output Node Properties - FTE Output 




Description 


uesunacion 


Ftacir 


Agent 





Request 


Queue manager 


Records and Elements 


File directory 


Validation 





File name* *.txt| 

1 

Monitoring 


For example; test,txt or * Ixl 



Ootions 



Figure 8-39 Setting FTEOutput node properties 


Other FTE transfer parameters (for example, the destination agent name) are filled in 
dynamically at runtime using the Compute node. See section “Composing an FTE reply 
message from aggregated replies” on page 432 for more information. 


8.5.5 Using aggregation in WebSphere Message Broker 

Some business scenarios require request/reply processing with multiple replies (fan-out and 
fan-in). This design also provides an opportunity for an improvement in response time 
because slow requests can be performed in parallel and do not have to follow each other 
sequentially. If the subtasks can be processed independently, and do not have to be handled 
as part of a single unit of work, they can be processed by separate applications. 

Aggregation nodes automatically perform the task of synchronizing multiple requests and 
their incoming replies. This saves a lot of work compared to coding multiple MQGet nodes in 
the flow for storing the state of the processing. 

During the fan-out process (the upper part of the message flow in Figure 8-32 on page 419), 
some control information is stored automatically in the LocalEnvironment by the 
AggregateControl, AggregateRequest, and MQOutput nodes. A special folder named 
ComlbmAggregateControlNode is used for this information. Additionally, the AggregateRequest 
nodes store information about awaited requests in the broker database. 

You can either create the fan-out and fan-in flows in the same message flow or in two different 
message flows. In either case, the two parts of the aggregation are associated by setting the 
Aggregate Name property. A single flow is easier to implement for a simple case, but there 
are some limitations to this approach, and, in most cases, you will find that the flexibility 
offered by two message flows is preferable. The two flows can be modified independently of 
each other. The two flows can also be stopped and started independently of each other. The 
two flows can also be deployed to separate execution groups to take advantage of 
multiprocessor systems, or to provide data segregation for security or integrity purposes. 

AggregateControl node 

After all request messages are sent, the control information is propagated from the 
AggregateControl node to the AggregateReply node in the fan-in process. 

AggregateReply node 

Any incoming reply from the MQInput node is recorded by the AggregateReply node and 
stored until all outstanding replies have arrived or a timeout occurs. Next, the AggregateReply 
node composes a logical message tree with multiple bodies. Each reply is contained in 
separate body folder, which is identified by the request name. 
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Handling transactions in aggregation nodes 

As shown in Figure 8-40, an aggregation flow is a complex application that involves multiple 

transactions (units of work): 

1 . In a fan-out flow, the first logical unit of work ends when all requests are sent and the 
automatic control message is put onto the SYSTEM. BROKER.AGGR. CONTROL queue. 

2. In a fan-in flow, there is a logical unit of work for each incoming reply while aggregating 
from the MQInput node to the AggregateReply node. 

3. This is similar to step 2, where there is a logical unit of work for each incoming reply while 
aggregating from the MQInput node to the AggregateReply node. 

4. For the aggregated result message, a new logical unit of work starts in the 
AggregateReply node (which has a TransactionMode property) when all replies have 
arrived or the timeout interval is expired. 



Figure 8-40 Handling transaction in Aggregation nodes 


These are only the logical units of work in a message flow. There are additional logical units 
of work during MQ transport, and in those applications that consume the requests and send 
replies to the fan-in flow. 

Composing an FTE reply message from aggregated replies 

The aggregation message arrives on the output terminal of AggregateReply node. It consists 
of multiple messages under the ComlbmAggregateReplyBody root element. Notice that all 
messages can be in different parser domains, and they appear in the same order as they 
arrive at the input terminal of the AggregateReply node, which might not be the order you 
expected. Note that we have a REPORT folder for replies from the RDW application and 
several OPERATION folders, one for each reply from the VAS application, as shown in 
Figure 8-41 on page 433. (Note that Figure 8-41 on page 433 was captured from the 
debugger in Message Broker Toolkit after a breakpoint was set right after the AggregateReply 
node). 
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Name 

Value 

- r Message 


+1 Q Properties 


- Q ComlbmAggregateReplyBody 


□ ^ OPERATION 


S $ Properties 


+ ^ MQMD 


□ XMLN5C 


□ # branch 


f branch_number 

1 

date 

1.3.2012 

□ ^ operation 


^ transactionID 

1917 

& symbol 

IBM 

^ price 

1.901E+2 

& amount 

20 

^ commission 1 

p3 , BE- 1 

& commissionZ 

3E-2 

□ ^ DB 


^ Id 

754 

^ result 

00000000-0000-0000-0000-000000000000 

S OPERATION 


+] ^ OPERATION 


□ ^ REPORT 


+ Properties 


:+: $ MQMD 


H + DFDL 


- sr FTERecordSample 


+ ^ branch 


+! ^ customer 


+ report 


^ LocalEnvironment 


^ Environment 


^ ExceptionList 



Figure 8-4 1 AggregateReplyBody tree 


To construct a DFDL message from all of the replies, we use ESQL to deal with complex 
message structures. 

Double-click the Combine Results node to view the code and replace the original content of 
the FTESampleFlow_Combine_Results module with the text in Example 8-1 1 . 

Example 8-11 ESQL module FTESampleFlow_Combine_Results 

CREATE COMPUTE MODULE FTESampl eFl ow_Combi ne_Resul ts 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

CALL CopyEnti reMessage() ; 

declare report_fol der reference to 
InputRoot .ComlbmAggregateReplyBody . REPORT ; 

set OutputRoot. ComlbmAggregateReplyBody = null; 
create lastchild of OutputRoot domain 'DFDL' name 'DFDL 1 ; 
set OutputRoot. Properties. MessageType = 1 FTERecordSample 1 ; 
set OutputRoot. DFDL. FTERecordSample = report_fol der. DFDL. FTERecordSample; 
create previoussibl ing of OutputRoot. DFDL. FTERecordSample. report name 
'operations ' ; 

set OutputRoot. DFDL. FTERecordSample. operations. operation[] = select 
O.XMLNSC. branch. operation. transactionID as transactions, 

O.XMLNSC. branch. operation. symbol as symbol. 
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cast(O.XMLNSC. branch. operation. price as float) as price, 
cast(O.XMLNSC. branch. operation. amount as float) as amount, 
cast(O.XMLNSC. branch. operation. commissionl as float) as commissionl, 
cast(O.XMLNSC. branch. operation. commission2 as float) as commission2, 

O.XMLNSC. branch. operation. result as registeredID 
from 

InputRoot.ComIbmAggregateReplyBody.OPERATION[] AS 0; 

set OutputLocal Environment. Destination. FTE.DestinationAgent = ' I TS0_B 1 ; 

declare FTE_Params reference to OutputLocal Envi ronment.Desti nation. FTE; 
set FTE_Params.DestinationQmgr = ' QM_FTE ' ; 

set FTE_Params. Directory = 'c:\ITSO\agent_b_out'; 

set FTE_Params.Name = THE ( 

SELECT ITEM F.file_name 
FROM Database. FI LE_STATUS as F 

WHERE F.report_msg_id = cast(report_folder.MQMD.Correl Id as CHAR)); 
set FTE_Params. Overwrite = true; 

RETURN TRUE; 

END; 

CREATE PROCEDURE CopyEntireMessageQ BEGIN 
SET OutputRoot = InputRoot; 

END; 

END MODULE; 


1 . In this module, we first copy content from the input to the output message and cut a 
ComlbmAggregateReplyBody subtree from it. 

2. We then create the FTERecordSample root element and copy to it all elements from the 
REPORT folder message body. 

3. An interesting part of this code is done by the sel ect ESQL statement. This sel ect takes 
all OPERATION folders and extracts from them every child of the operation element. The 
folders are then taken into the destination operation subtree with the same names except 
the result element, which is renamed to registeredID to comply with FTERecordSample 
message definition. 

4. The remaining code dynamically overrides the parameters for the FTEOutput node in 
order to send messages to the ITSO_B FTE agent. 

5. The names of the destination files are the same as the source names and are taken from 
the database. 


Note: You have to specify a remote queue manager name for your transfer, even if your 
source agent’s queue manager and coordination queue manager are the same. This is 
why we specified QM_FTE as the DestinationQmgr. 


8.5.6 Producing multiple messages from the compute node 

Double-click the Route node and replace the original content of the FTESampleFlow_Route 
module with the text in Example 8-12 on page 435. 
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Example 8-12 ESQL Module FTESampleFlow_Route 


CREATE COMPUTE MODULE FTESampl eFl ow_Route 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

CALL CopyEntireMessageQ ; 

set OutputRoot.DFDL.FTERecordSample. operations = null; 
propagate to terminal 'out' delete none; 

set OutputRoot.DFDL.FTERecordSample. report = null; 
declare operation reference to 
InputRoot . DFDL. FTERecordSampl e . operati ons . operati on [1] ; 
set OutputRoot.DFDL = null; 

set OutputRoot.XMLNSC. branch = InputRoot. DFDL. FTERecordSampl e. branch; 

while lastmove(operation) do 

set OutputRoot.XMLNSC. branch. operation = operation; 
set OutputRoot.XMLNSC. branch. operation. DB = Envi ronment .DB; 
propagate to terminal 1 out 1 1 delete none; 
move operation nextsibling repeat type name; 
end while; 


RETURN FALSE; 

END; 

CREATE PROCEDURE CopyEnti reMessage () BEGIN 
SET OutputRoot = InputRoot; 

END; 

END MODULE; 


The code in this module first copies the entire content from the input message to the output 
message, and then it deletes the operations subtree (see the logical model in Figure 8-36 on 
page 425). Next, the module sends the message with the report part to the out terminal using 
the propagate to terminal statement. 

After that, we used an operation cursor (reference) in a while cycle with a move operator to 
build a portion of source message for each operation and route these parts to the terminal 
outl. 

At the end, the code returns fal se which tells the broker that the message has been handled 
properly and it is does not need to be propagated it to the default out terminal again. 


8.5.7 Accessing databases from the database nodes 

The database node is a general purpose place to execute operations against a database. You 
cannot modify content of the message in this node like you can in a compute node, for 
example, but you can execute selects, inserts, updates, and other SQL statements. 

In our scenario, we use a database node for tracing, for storing the state of the flow, and for 
correlating responses with original information. For instance, we assume that the RDW 
application has a predefined XML format that does not allow us to put a file name information 
in the message. So upon receiving a reply from RDW, we pick up the file name information 
from the database using the message correlation information as a foreign key. 
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Log File status node 

Double-click the Log File status node and replace the original content of the 
FTESampleFlow_Log_File_Status module with the text in Example 8-13. 

Example 8-13 ESQL Module FTESampleFlow_Log_Fi le_Status 

CREATE DATABASE MODULE FTESampl eFl ow_Log_Fi 1 e_Status 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

Declare FTE_Params reference to Local Envi ronment. FTE. Transfer; 

Declare FTE_Rec reference to Root.DFDL.FTERecordSample; 

INSERT INTO Database. FILE_STATUS (file_name, parts_i n_total ) 

VALUES (FTE_Params.Name, cardinality(FTE_Rec. operations. operation[]) + 1); 

Declare ids ROW; 

set ids = PASSTHRUC Select id FROM FILE_STATUS WHERE id = @@IDENTITY 1 ) ; 

Set Environment. DB. Id = ids. id; 

RETURN TRUE; 

END; 

END MODULE; 


This code inserts general information about the received file into the FILE_STATUS table and 
stores an auto-generated value from the id column in the Environment. DB. Id subtree for later 
use. 

To get file information, such as the file name, the code uses metadata stored by the FTEInput 
node at the LocalEnvironment.FTE.Transfer subtree. The code also counts the number of 
operations contained within the message using the cardinality function. 

Store Msg Id node 

Double-click the Store Msgld node, and replace the original content of the 
FTESampleFlow_Store_Msgld module with the text in Example 8-14. 

Example 8-14 ESQL Module FTESampleFlow_Store_Msgld 

CREATE DATABASE MODULE FTESampl eFl ow_Store_MsgId 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

Declare MQ_Id BLOB 

Local Envi ronment. Wri ttenDesti nation.MQ.Desti nationData. msgld; 

Update Database. FILE_STATUS as F 

Set report_msg_id = cast(MQ_Id as CHAR) 

Where F.id = Environment. DB. Id; 

RETURN TRUE; 

END; 

END MODULE; 


This code stores the information about the message that was sent to the RDW application, 
into the database. The msgld of the message is generated by the MQOutput node and put 
into the LocalEnvironment.Writtendestination.MQ subtree. The primary key for this operation 
is taken from the Environment. DB subtree where it is stored by the Database node, as 
described in “Log File status node” on page 436. 
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Update Reps Status node 

Double-click the Update Reps Status node, and replace the original content of the 
FTESampleFlow_Update_Reps_Status module with the text in Example 8-15. 

Example 8-15 ESQL Module FTESampleFlow_Update_Reps_Status 

CREATE DATABASE MODULE FTESampleFlow_Update_Reps_Status 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

Declare corrID CHAR Root.MQMD.Correl Id; 

UPDATE Database. FI LE_STATUS as F 

SET parts_processed = F.parts_processed + 1, last_modified = 
CURRENT_TIMESTAMP 
WHERE 

F. report_msg_id = corrID; 

RETURN TRUE; 

END; 

END MODULE; 


The MQReply node in the emulated applications returns the original msgld information in the 
Correlld field of the message. This is the default behavior of an MQReply node. The Correllld 
is used in the AggregateReply node. In the Update Reps Status database node, we also use 
the Corrlld information to update the number of received replies in FILE_STATUS table. 


Update statement peculiarities: Note that you cannot use F. alias of the FILE_STATUS 
table at the left side of the assignment in the SET operator. But at the same time, you have 
to use F. alias at the right side of the assignment. This is a syntax rule of the ESQL update 
statement. 


Update Ops status node 

Double-click the Update Ops status node, and replace the original content of the 
FTESampleFlow_Update_Ops_Status module with the text in Example 8-16. 

Example 8-16 ESQL Module FTESampleFlow_Update_Ops_Status 

CREATE DATABASE MODULE FTESampl eFl ow_Update_Ops_Status 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

UPDATE Database. FI LE_STATUS as F 

SET parts_processed = F.parts_processed + 1, last_modified = 
CURRENT_TIMESTAMP 
WHERE 

F.id = Root. XMLNSC. branch. operation. DB. Id; 

RETURN TRUE; 

END; 

END MODULE; 


This node performs the same actions that the Update Reps Status node performs; however, 
in this case, the original primary key ID information is returned by the VAS emulator 
OperationApplicationClient message flow. Because OperationApplicationClient is emulating a 
broker-managed wrapper for a real .NET client, we can use any format to interact with it, so 
we put information about the database ID into the message payload of the request and send 
it back in response. 
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Complete File status node 

Double-click the Complete File Status node and replace the original content of the 
FTESampleFlow_Complete_File_Status module with the text in Example 8-17. 

Example 8-17 ESQL Module FTESampleFlow_Complete_File_Status 

CREATE DATABASE MODULE FTESampl eFl ow_Compl ete_Fi 1 e_Status 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

Declare corrID CHAR Root .ComlbmAggregateReplyBody . REPORT. MQMD.Correl Id; 
UPDATE Database. FI LE_STATUS as F 

SET completed = 1, last_modified = CURRENT_TIMESTAMP 
WHERE 

F.report_msg_id = corrID; 

RETURN TRUE; 

END; 

END MODULE; 


In the Complete File Status node, we pick up Correlld information from the REPORT folder of 
the aggregated reply message. We then use Correlld to update the number of received 
replies in FILE_STATUS table. 


8.5.8 Creating the queues for the FTESample application 

Execute the two commands in Example 8-18 from the command line to create the queues for 
replies from the RDW and VAS application emulators. 

Example 8-18 DEFINE QLOCAL commands 

echo DEFINE QL0CAL(0PTN. IN) | runmqsc QM_ITS0 
echo DEFINE QLOCAL(REPT. IN) j runmqsc QM_ITS0 


8.6 Running the scenario 

Use the following procedure to run the scenario: 

1 . Deploy all three applications to BKRJTSO, as shown in Figure 8-42. 

E-flg Brokers 

I P' S 

- ITSO 
j +]-£S] FTESample 
MOCKS 

+ §d OperationsApplicationClient 
4l-S ReportsApplication 

Figure 8-42 Brokers view 

2. Ensure that a file transfer exists in the Pending Transfers category of the Managed File 
Transfer subtree in WebSphere MQ Explorer. 

3. Create a file named branch_f i 1 e . txt from Example 8-1 0 on page 428, and save it in the 
c:\ITSO\folder, if it is not already created. 
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4. Copy this file into to the c:\ITSI\agent_a_out directory and wait about one minute for the 
file to process. If everything goes right, you will see the two entries shown in Figure 8-43 in 
the Transfer log category of Managed File Transfer. 


Job Name | Source 

| Destination 

| Completion State 

| Started (America/New York) 

ITSO_A 

BRKJTSO.ITSO 

Successful 

3/29/12 4:37:36 PM EDT 

ITSO BRKJTSO.ITSO 

ITSO_B 

Successful 

3/29/12 4:37:37 PM EDT 


Figure 8-43 File transfers succeeded 


The first line tells you that file was successfully transferred from ITSO_A agent to the brokers 
embedded agent BRK_ITSO.ITSO. The second log entry tells you that the file was delivered 
from BFIKJTSO.ITSO to the ITSO_B FTE agent, so it successfully passed through the 
FTESample message flow. Notice the ITSO job name is the result of the work of the ESQL 
module described in “Composing an FTE reply message from aggregated replies” on 
page 432. 


Note: The set of columns in Figure 8-43 differs from the default setup. You can customize 
the columns using the Configure Agent Status Columns icon in the toolbar at the right-top 
corner of WebSphere MQ Explorer window. 


5. Look at the file branch_file in the c:\ITSO\agent_b_out directory. It must be similar to 
Example 8-19. 

Example 8-19 Transformed version of branch_file. txt 

BRANCH#]., DATE 1.3.2012 
CUSTOMER ID: R90306 
OPERATIONS 

1917, IBM, 190.1, 20, 0.38, 0.03,00000000-0000-0000-0000-000002001917 
1945, IBM, 190.5, 20, 0.38, 0.03,00000000-0000-0000-0000-000002001945 
1976, IBM, 190.99, 10, 0.38, 0.03,00000000-0000-0000-0000-000001001976 

END OF OPERATIONS 

REPORT 

STOCKS 

IBM, 100, 150, 50 
END OF STOCKS 
COMMISSION 
1.14, 0.09, 1.23 
CASH 

1000000, 990476.87, -9523.13 


Notice the recordedID added at the end of each operation in bold, which means that the VAS 
emulator successfully executed the .Net operation within OperationsAppCl ient.dl 1 . 


8.6.1 Troubleshooting tips 

If something goes wrong, we recommend that you first check the Windows Application events 
in the Events Viewer of the Administrative Tools for any specific errors from the broker. 
Starting with the Event Viewer is a useful practice because the viewer collects all different 
types of errors, such as database connection failures, WebSphere MQ communication 
problems, messages rolled back to queues, and so on. 

Another place to look is the WebSphere MQ Explorer. Because we have not implemented any 
error handling mechanisms, messages can become stuck in the message queues in the 
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event of an error. If this happens, stop all of the flows, and clean up the queues. Next, analyze 
the root cause of the error again by looking for the events in the Event Viewer. 


8.6.2 Exploring the work of the scenario 

In this section, we use the debugger in the Message Broker Toolkit to explore how the 
message moves through the flow. 

Setting up debug 

Right-click the ITSO execution group, and select Launch Debugger. Message Broker 
Toolkit will ask you to enter the value for the debug port. You can enter, for example, 14111 or 
another value you think is suitable, and click OK. 

Examining the Route node 

You can use breakpoints to examine how messages flow through the Route node: 

1 . Add break-points to your flow by right-clicking the Route node and choosing Add 
Breakpoints After Node. Wait a minute for repeating transfers to occur again. You will 
see that this time the flow execution stops between the Route and Reports nodes. 

2. Examine the content of the message using the Variables view. You can see that there is 
only a report section there. Press F8 or the Resume button in the Debug view, and notice 
that the next flow stops between the Route and Operations nodes. 

3. Examine the message structure again and notice the difference. You can then continue 
using F8 to continue through the flow, ensuring that it acts as you expect. 

4. Remove the breakpoints by right-clicking them and choosing the Remove breakpoint 
option. 

Examining the Aggregate Reply node 

You can use breakpoints to examine how messages flow through the Aggregate Reply node: 

1 . Add breakpoints before and after the Aggregate Reply node and wait until replies from 
RDW or VAS arrive. Delete the branch_fi 1 e.txt from the agent_a_in folder to stop the 
repeatable transfers. 

2. Examine the message structure in the Message Broker Toolkit’s Debug perspective, and 
press F8 to resume the message flow execution. Notice that there are three replies from 
the VAS application and one from RDW in total. 

3. After processing all of the replies, the message flow proceeds to the output terminal of the 
Aggregate Reply node. Examine the message structure at this point. It should contain all 
four replies. 

4. Step over the Complete File Status and Combine Results nodes by pressing F6 (Step 
over) twice. Examine the message structure at the output terminal of the Combine Results 
node and notice the logical structure of the result message. You should also see under the 
LocalEnvironment subtree an overrides values for the FTE Output node. 

Examining the logging process 

You can put breakpoints after each database node to trace the flow from a database 
perspective. When the flow stops, use a database utility to execute a SELECT FROM 
statement with the Id field. This value is stored in Environment.DB.Id field in the Fan-out part 
of the flow, and can be seen from the Variables view. See Example 8-20 on page 441 . 
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Example 8-20 Select for FILEJNFO table 

select * from FROM FILE_STATUS WHERE id = **YOUR_VALUE_HERE** 


8.7 Extending the scenario 

For simplification, we did not implement error handling in this scenario. For production-ready 
systems, error handling is a required functionality, so add error handling logic in your FTE 
integration message flows. 

Another topic that was not covered in this chapter is a new function in this version of the 
broker to produce monitoring events from the flow without coding the events. You can use a 
configuration of the node properties to select information to be stored in the database. This 
functionality can be used instead of coding the multiple database nodes we have in our flow. 
Before WebSphere Message Broker Version 8, that kind of functionality was typically 
reinvented for each integration project. Now, this functionality is built into the broker. 
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Integrating file transfer using 
Sterling Connect:Direct with your 
message flow 


This scenario illustrates the use of WebSphere Message broker to fetch a file transferred by a 
remote Sterling Connect:Direct server, process multiple transactions in the file one-by-one, 
validate each transaction, log the request into a file, and process them to its destination. 

Specifically, we cover the following topics in this chapter: 

► Scenario overview 

► Overview of the Sterling Connect:Direct 

► Using WebSphere Message broker with Connect:Direct 

► Preparing the Connect: Direct environment 

► Configuring WebSphere Message Broker 


Additional materials: The WebSphere Message Broker project interchange file and the 
.NET class code for this scenario can be downloaded from the IBM Redbooks publication 
web site. See Appendix A, “Additional material” on page 485 for more information. 


© Copyright IBM Corp. 2012. All rights reserved 
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9.1 Scenario overview 


A banking firm has a number of branches that handle the day-to-day banking transactions of 
their customers. These transactions can be a utility bill payment, an order of fixed deposits, a 
withdrawal request, a deposit request, and so on. At the end of the business day, the bank 
branch generates a report file containing a consolidated list of transactions for their clearance. 
Sometimes these reports are generated immediately based on the business need and sent to 
the core banking system for clearance. The consolidated report file is sent to the Sterling 
control center system. 

The Sterling control center collects and manages files arriving from different branches. A 
WebSphere Message Broker flow at the head branch office receives each file that arrives at 
the Sterling control center. In this solution, the Sterling Control center is an intermediate 
system between different branches and the head branch office. 

The message flow receives the file and parses each transaction record in the file one-by-one. 
Each transaction record is logged into a data warehouse using WebSphere MQ and validated 
in the message flow. If the validation is successful, the transaction record is sent to the core 
banking system for clearance. The message broker receives the response from the core 
banking system for each transaction request and sends a reply back to the requested branch 
as a report file. See Figure 9-1 . 



Figure 9- 1 WebSphere Message Broker integration with Sterling Connect: Direct scenario 


This scenario assumes that the following components are installed and configured: 

► Server-A: 

- IBM Sterling Connect: Direct V4.5.0.1 is installed and configured a node called 
BRANCH-A. 

► Server-B 

- IBM Sterling Connect:Direct is installed and configured a node called BRANCH-A. 

► Server-C 

- IBM Sterling Connect: Direct has been installed and configured a node called 
CENPROC. 
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► Server-D: 


- WebSphere MQ is installed. A WebSphere MQ queue manager is defined and a local 
queue named LOGQ is created. 

- WebSphere Message Broker V8 is installed. A broker named ITSOBROKER is 
created. 

- IBM DB2 is installed. 


9.2 Overview of the Sterling Connect: Direct 

Sterling Connect:Direct is the point-to-point file transfer software optimized for high-volume, 
secure, and assured delivery of files within and among enterprises. Sterling Connect:Direct 
can deliver your files with: 

► Predictability: Assures delivery through automated scheduling, checkpoint restart, and 
automatic recovery/retry. 

► Security: Ensures that your customer information stays private and that your file transfers 
are auditable for regulatory compliance through a proprietary protocol, authorization, and 
encryption (FIPS 140-2, and Common Criteria certified). 

► Performance: Handles your most demanding loads, from high volumes of small files to 
multi-gigabyte files. 

Figure 9-2 on page 446 shows how Connect: Direct Nodes can communicate with each other 
using Requester or the Connect:Direct client. 
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Peer-to-Peer and Client/Server 
Concepts in Connect: Direct 


This Connect: Direct node 
initiates the connection. 
Therefore, it is the primary 
node (PNODE). 


This Connect: Direct node 
is being contacted for the 
connection. Therefore, it is 
the secondary node (SNODE) 



Each Connect: Direct node is configured with a host port 
and an API port. The host port listens for connections 
from other Connect: Direct nodes. The API port listens for 
connections from its client, in this case, from the requester. 


Because this node is the SNODE, its client is not 
involved in this session. However, the client can still 
interact with the server to issue commands and 
processes that are not related to this session. 


Whether a Connect: Direct node is the PNODE or SNODE 
applies only to which node initiates the connection. It does 
not denote the direction of the data transmission. 


Figure 9-2 Connect: Direct nodes 


Each Connect:Direct node is configured with a host port having a default value of 1364 and 
an API port having the default value of 1363. The host port listens for a connection from other 
Connect: Direct nodes. The API port listens for connections from its client, called a Requester. 
Whether a Connect:Direct node is a primary node (PNODE) or secondary node (SNODE) is 
determined by which node initiates the connection. In Figure 9-2, steps 1, 2, 3 show how a 
client sends a command to transfer a file from one Connect: Direct node to another. 


9.3 Using WebSphere Message broker with Connect: Direct 

WebSphere Message Broker can receive a file when any local or remote Connect: Direct file 
transfer is performed. Similarly WebSphere Message broker can send a file to a local or 
remote Connect: Direct server. Figure 9-3 on page 447 shows how a broker sends a file from 
a Windows Connect:Direct server to a UNIX Connect:Direct server using the CDOutput Node 
in a message flow. 

In Figure 9-3 on page 447, the WebSphere Message Broker CDOutput node is a requester 
that sends a file transfer command to API port on Windows Connect:Direct. The 
Connect: Direct server on Windows acts as the PNODE and does the file transfer to the UNIX 
Connect: Direct server (the SNODE in this case). The message broker CDOutput node needs 
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the SNODE name, host address, and API port to connect to the SNODE server and the 
destination file path for the transferred file. 


CD-S 


API port 


CD-R 


1 ' 


MQ Input 


JSl □ 

\m\ " 


CD Output 


MQ Inputl 


CD-S 





UNIX Command 
Line Client (CLI) 


Figure 9-3 Message broker file send from Windows to UNIX 


9.4 Preparing the Connect:Direct environment 

The scenario in this section has two Connect:Direct server nodes at the branches, referred to 
as BRANCH-A and BRANCH-B. A third Connect: Direct server node that acts as the Sterling 
control center, referred to as CENPROC, resides on Server-C. All are Windows servers. An 
assumption is made that the Connect:Direct servers are installed and configured for local file 
transfers. 

The following steps show the configuration required to enable a remote file transfer from 
BRANCH-A node to CENPROC node and from BRANCH-B node to CENPROC node: 

1 . Add a netmap entry for the CENPROC node in BRANCH-A’s netmap: 

a. In the CD Requester, right-click BRANCH-A, and select Admin Netmap. 

b. In the window that opens for NetMap, right-click and select Insert. 

c. In the Netmap Node Properties window, select the Main tab, enter the node name, and 
choose the operating system from the drop-down for the remote node. In this scenario, 
the name is CENPROC, and the operating system is Windows, as shown in Figure 9-4 
on page 448. 
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Figure 9-4 Netmap Main settings for Branch-A 

d. Select the TCP/IP tab, and enter the Host/IP Address. We used xxx.yyy.zzz.aaa, which 
is the IP address of Server-C, as shown in Figure 9-5 on page 449. 
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Figure 9-5 Netmap TCP/IP settings for Branch-A 

e. Select the Communication Paths tab, and select the existing TCPCommPath, as 
shown in Figure 9-6 on page 450. 
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Figure 9-6 Netmap Communication Paths settings for Branch-A 

f. Click OK. 

g. Right-click CENPROC, and click Apply. 

2. Repeat step 1 to add a netmap entry for the CENPROC node in BRANCH-B’s netmap. 

3. Add a netmap entry for BRANCH-A in CENPROC’s netmap: 

a. In the CD Requester, right-click CENPROC, and select Admin -» Netmap. 

b. In the window that opens for NetMap, right-click and select Insert. 

c. Perform the following actions in the Netmap Node Properties window: 

i. Under the Main tab, enter BRANCH-A as the node name, and select Windows as the 
operating system from the drop-down for the remote node (see Figure 9-7 on 
page 451). 
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Figure 9-7 Netmap Main settings for Server-C 

ii. Select the TCP/IP tab, and enter the IP address for the BRANCH-A machine and 
the port number for BRANCH-A (1364), as shown in Figure 9-8 on page 452. 
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Connect:Direct - Netmap for CENPROC 


File Edit View Node Netmap Tools Admin Window Help 
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Netmap for CENPROC 



Figure 9-8 Netmap TCP/IP settings for Server-C 

iii. Select the Communication Paths tab, and select the existing TCPCommPath, as 
shown in Figure 9-9 on page 453. 
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Figure 9-9 Netmap Communication Paths settings for Server-C 


d. Click OK. 

e. Right-click CENPROC, and click Apply. 

4. Repeat step 3 to add a netmap entry for BRANCH-B in CENPROC’s netmap. 

Now BRANCH-A and BRANCH-B are ready for remote file transfers with the Sterling control 
center node CENPROC. 


Authorization: In this scenario, the same user ID and password used for the transfers is 
defined at all three systems. If the user ID and password are different on the systems, you 
either need to add functional authorities or specify the system user ID and password of the 
primary and secondary nodes in the CONNECT:DIRECT process definition. 


9.5 Preparing the logging database 

The message flow logs transactions to a DB2 database. Use these instructions to prepare the 
database: 

1 . Create the database ITSODB in DB2 using the Control Center. See Figure 9-10 on 
page 454. 
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9ct Control Center - DB2COPY1 
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Figure 9-10 Creating the database 


Alternatively, you can use the following DB2 command to create the database: 
C:\>db2 create database ITSODB 

2. Make sure the DSN name is created using ODBC Data Source Administrator. See 
Figure 9-11. 


:,P ODBC Data Source Administrator 

User DSN System DSN | File DSN | Drivers | Tracing | Connection Pooling | About | 
System Data Sources: 


Name 


Driver 


Connect: D irect v4. 5. 01 M essages S Q L S er ver N ati ve Clien 
Connect: D irect v4. 5. 01 T cqS tats S Q L S er ver N ati ve Clien 
CUSTOMER IBM DB2 ODBC DRIVEF 


Add... 


Remove 


ODBC IBM DB2 Driver - Add 




Select the DB2 database alias you want to register for ODBC, 
or select Add to create a new alias. You may change the 
data source name and description, or accept the default. 


Data source name |lTS0DB| 
Database alias | ITSODB 
Description 


T | Add | 


OK 


Cancel 


Configure... 


how to connect to 
isible to all users 


Help 


Figure 9-11 Creating the ODBC driver 


3. Create the TRANSLOG table. Select Tables -» Create, as shown in Figure 9-12 on 
page 455. 
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Fo Control Center - DB2C0PY1 

Control Center Selected Edit View Tools Help 


& e s 

Q Object View 

Control Center 
(j - Q All Systems 
(=)■■■ Q All Databases 
i- 0 CUSTOMER 
0 ITSODEi 


+ 


& Table 
Q View 
■Q Alias 
C3 Nickr 
C3 Cact 


Create... 

Create From Import... 
Filter 

Refresh 


► 


Figure 9- 12 Creating a table 


4. Select a Table schema and provide a Table name, as shown in Figure 9-13. 



Figure 9-13 Defining a table schema and name 
5. Add the columns shown in Figure 9-14 to the table. 


B Table - TRANSLOG 

Schema : DB2ADMIN 

Creator : DB2ADMIN 

Columns : 8 

Actions: 

Open 
p“| Query 

Colun 

Key 

ins 

Name 

Data type 

Length | Nullable 



NAME 

CHARACTER 

To Wo 


ACCOUNT_NO 

BIGINT 

8 INo 


T 0_ACC0UNT_N0 

BIGINT 

8 No 


T 0_BR ANCH_N AME 

CHARACTER 

[To [no 

Show Related Objects 


TO_IF5C_CODE 

INTEGER 

4 

No 


AMOUNT 

BIGINT 

8 | 

m 

Create NewTable 


DATE 

DATE 

4 No 


TRAN5JD 

BIGINT 

8 |ves 




Figure 9-14 Adding columns to a table 


Alternatively, you can use an equivalent SQL command to create the table, as shown in 
Example 9-1 . In this example, the system user is db2admin. Replace it with your own 
system user. 

Example 9- 1 SQL command for creating a table 
CONNECT TO ITSODB USER "db2admi n" ; 
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CREATE TABLE DB2ADMIN. TRANSLOG ( NAME CHARACTER (10) NOT NULL , ACCOUNT_NO 
BIGINT NOT NULL , TO_ACCOUNT_NO BIGINT NOT NULL , TO_BRANCH_NAME CHARACTER 
(10) NOT NULL , TO_IFSC_CODE INTEGER NOT NULL , AMOUNT BIGINT NOT NULL , 
DATE DATE NOT NULL , TRANSJD BIGINT NOT NULL , CONSTRAINT CC1332485 1297 16 
PRIMARY KEY ( TRANSJD) ) ; 

CONNECT RESET; 


9.6 Configuring WebSphere Message Broker 

The next step is to configure the WebSphere Message Broker on Server-D to process the 
files coming into the CENPROC node. This includes creating a configurable service and 
creating the message flow. 


9.6.1 Creating a configurable service on WebSphere Message Broker 

In this scenario, WebSphere Message Broker and the CENPROC node are on different 
machines, so a configurable service must be created on WebSphere Message Broker to 
process remote file transfers. Before starting the configuration, ensure that the directory to 
which file transfers occur on Server-C is mounted and is accessible on the machine where 
WebSphere Message Broker is installed. In this scenario, the file transfers go to the 
C:\EnterpriseDataCenter\TransactionFiles directory on Server-C. So, the TransactionFiles 
directory is shared. 

The brokerPathToinputDir key of the CDServer configurable service then takes the value: 
HIP Address of Server-C>/TransactionFi 1 es 

On UNIX systems, this value is the mounted path, and the IP address in not required, for 
example: /mnt/TransactionFiles, where mnt is the mount point on the broker system. 

The cdPathToinputDir key takes the value C:\EnterpriseDataCenter\TransactionFiles. 

Use WebSphere Message Broker Explorer to create the configurable service, as described in 
this procedure: 

1 . In the IBM WebSphere MQ Explorer, right-click broker_name -» Configurable Services, 
and select New Configurable Service. 

2. In the window that opens, enter a Name, for example CDConf i gurabl eServi ce. 

3. Select CDServer for the Type from the drop-down. 

4. Enter the appropriate values for the keys in the table, as shown in Figure 9-1 5 on 
page 457. In this example: 

- brokerPathToinputDir: IP Address of Sen/er-C\TransactionFiles 

- cdPathToinputDir: C:\EnterpriseDataCenter\TransactionFiles 

- hostname: IP Address of Server-C 

- port: 1363 

- securityldentity: cenproc 
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Figure 9-15 Creating Configurable Services for Broker on Server- D 


Creating the service with a command: An alternative to using the WebSphere 
Message Broker Explorer to create the service is to use the following command: 

mqsicreateconfigurableservice broker name -c CDServer -o 
CDConfigurableService -n brokerPathToInputDi r, brokerPathToStagi ngDi r, 
cdPathToInputDi r, cdPathToStagi ngDi r, hostname, port, queuePrefix, 
securityldentity -v IP Address of Seri/er-C\TransactionFiles, , 
C:\EnterpriseDataCenter\TransactionFiles, , IP Address of Server-C , 1363, , 
cenproc 


5. Configure the securityldentity CENPROC used in the CDConfigurableService. Open a 
command window, and enter the following command with the necessary values: 

mqsi setdbparms BrokerName -n CD:: cenproc -u username-of-Server-C-machine -p 
password-of-Server-C-machine 

The value for username-of-Server-C-machine is the system user name of 
Server-C-machine where the CD Server is started. 
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Note: The default configurable service is used and default securityldentity setup is needed 
as the local file transfers are set up. For default securityldentity, use the following command 
with the proper values: 

mqsi setdbparm <BROKERNAME> -n CD::default -u <username-of-broker-machine> -p 
<password-of-broker-machine> 


9.6.2 Creating the message flow 

The next step is to create and configure the message flow to process the files coming to the 
CENPROC Connect:Direct node. The message flow is shown in Figure 9-16. 



Figure 9-1 6 MessageFlow 


1 . A file containing one or more transaction records is transferred to a file system on 
Server-C. Here each transaction record in the file is in XML format and is delimited by end 
of line character. 

2. The CD InputReceivelnputFile node receives the file from that location and parses the file, 
using the end of line delimiter to determine where each record ends. 

3. Each transaction record is sent to the Flow Order node: 

a. The flow order node first sends the transaction to the LoggingSystem node, which puts 
the transaction on a message queue. The transaction is then picked by another flow to 
insert it into the Data warehouse. 

b. The flow order node then sends the transaction to the next node 
ValidateAndRouteToCoreBankingSystem for validation. 

4. The ValidateAndRouteToCoreBankingSystem node validates the transaction and sends 
the transaction to the next node. 

5. The TCPIPCIientOutput node sends the transaction out of the flow to the core banking 
system, which is simulated by a separate message flow (not shown in Figure 9-16). 

6. When the core banking system completes its processing, it sends back a successful 
response to the TCP/IP Client ReceiveFromCoreBankingSystem node. The transaction is 
then sent to the next node. 
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7. The SpecifyReplyFileNameUsingTransactionld Compute node creates a name for the 
transaction file based on the transaction ID. 

8. The CDOutput node transfers each successful transaction message into a report file with 
to the Connect Direct Server on the WebSphere Message Broker system. 


9.6.3 Creating the main message flow 

Develop the message flow shown in Figure 9-16 on page 458 for the scenario, and configure 
it using the following steps: 

1 . Open the Message Broker Toolkit. 

2. Create a new application called CDdemo. 

3. Create a new message flow called FileTransferCDToMsgFlow. 

4. Add the following nodes to the message flow, rename them, and wire them as indicated in 
Table 9-1. 


Table 9- 1 Message flow nodes 


Palette section 

Node type 

Node name 

Terminal x Wired to node y: 

File 

CDInput 

CD InputReceivelnputFile 

Out to Flow Order 

Construction 

FlowOrder 

Flow Order 

First to LoggingSystem 
Second to 

ValidateAndRouteToCoreBa 

nkingSystem 

WebSphere MQ 

MQOutput 

LoggingSystem 

None - message is put on the 
LOGQ queue 

Transformation 

Compute 

ValidateAndRouteToCoreBankingSystem 

Out to In terminal of 
TCP/IP Client 

OutputToCoreBankingSyste 

m 

TCP/IP 

TCPIPCIientOutput 

TCP/IP Client 

OutputToCoreBankingSystem 

Out to TCP/IP Client 

ReceiveFromCoreBankingS 

ystem 

TCP/IP 

TCPIPCIientReceive 

TCP/IP Client 

ReceiveFromCoreBankingSystem 

Out to In terminal of 

SpecifyReplyFileNameUsing 

Transactionld 

Transformation 

Compute 

SpecifyReplyFileNameUsingTransactionld 

Out to In terminal of CD 
OutputSendReplyFile 

File 

CDOutput 

CD OutputSendReplyFile 

None - end of flow 

WebSphere MQ 

MQInput 

LoggingSystemlnput 

Out to Database_Warehouse 

Database 

Database 

Database_DataWarehouse 

None - end of flow 
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The following steps show how to configure the message flow nodes: 

1 . Each transaction in the file BranchA.txt is parsed by the CDInput node CD 
InputReceivelnputFile using the end of line as a delimiter: 

a. Select the CD Input node and in the Properties view select the Basic tab and enter the 
following values: 

• Directory filter: The directory where the file transfers will take place 
\\<IPAddress of CENPROC node Server-C sys£em>\TransactionFi 1 es 

• Filter name filter: 

* 

An asterisk acts as a wild card and means that the CDInput node will pick up any 
input file. If the filter was set to * *.txt, the node picks up only the files with extension 
.txt. 

• Configurable service: CDConfigurableService 

This is the service created in 9.6.1 , “Creating a configurable service on WebSphere 
Message Broker” on page 456 

Figure 9-17 shows the Filters and Configurable service specified for this node. 


Properties 7 Problems B Deployment Log 

005 CD Input Node Properties - CD InputReceivelnputFile 

^ l 

Basic 

Input Message Parsing 

Enter values to determine how the node processes files transferred by IBM Sterling ConnectiDirect 

Filters 

Parser Options 

Directory filter \\<5ystem-C IP Address^TransactionFiles> 

Retry 

File name filter* * 

Records and Elements 


Validation 

CD Server 

Transactions 

Configurable service CDConfigurableService 



Action on successful processing No Action 




Figure 9-17 CD Input Node (1) 


b. Select the Input Message Parsing tab, and select the XMLNSC message domain, as 
shown in Figure 9-18. 


Properties £3 £ Problems 

B Deployment Log 


(j^ CD Input Node Properties - CD InputReceivelnputFile 


Description 


Basic 


Parser Options 


Retry 


Records and Elements 


Input Message Parsing 


Determine how the node parses the incoming messages 
Message domain 
Message model 
Message 
Physical format 


XMLNSC : For XML messages (namespace aware, validation, low memory use) 


<Leave blank to use XML schema in a Library or the Application, or select a M 


Browse... 


Message coded character set ID* Broker System Default 


Figure 9-18 CD Input Node (2) 


c. Set the Records and Elements delimiters, as shown in Figure 9-1 9 on page 461 : 

• Select Delimited for record detection. 

• Select DOS or UNIX Line End as the delimiter. 
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Select Postfix as the delimiter type. 


Properties S3 (£_ Problems B Deployment Log 


Ijfj CD Input Node Properties - CD InputReceivelnputFile 


Description 

Record detection 

Delimited 

Basic 

5kjp first record 

□ 

Input Message Parsing 

Length (bytes) 

80 

Parser Options 




Delimiter 

D05 or UNIX Line End 

Retry 



Records and Elements 

Custom delimiter (hexadecimal) 



Delimiter type 

Postfix 





Figure 9-19 CD Input Node (3) 


2. Each transaction is sent to the Flow Order node and first routed to the LogQ using the 
LoggingSystem MQ Output node (Figure 9-20). The transaction is then picked by another 
flow to insert it into the Data warehouse using the Database node Database 
DateWarehouse. 



Figure 9-20 


3. Select the LoggingSystem MQ Output node. In the Basic tab of the Properties, enter LOGQ 
as the queue manager name (Figure 9-21). 


[S Problems 

B Deployment Log Properties £3 

ill) MQ Out 

put Node Properties - LoggingSystem 


Description 

Basic 

Advanced 

Request 

Validation 

Monitoring 


Queue manager name 
Queue name 


LOGQ 


Figure 9-21 MQ Output properties 


4. Messages put on the LOGQ are then picked up by the LoggingSystem MQ Input node and 
sent to the Database_DataWarehouse node (Figure 9-22 on page 462). Select the node, 
and on the Basics tab enter LOGQ as the queue name. 
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jt Properties £3 

Dfj MQ Input Node Properties - LoggingSystem 
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Basic 


Queue name* LOGQ 


Input Message Parsing 


Parser Options 


Advanced 


Validation 


Security 


Figure 9-22 Database_DataWarehouse flow 


5. Select the Database_DataWarehouse node. 

a. In the Basic tab, enter ITSODB as the data source name, as shown in Figure 9-23. 


Graph User Defined Properties 
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Q Database Node Properties - Database DataWarehouse 


Description 


Basic 


Monitoring 


Data source ITSODB 

Connect before flow starts 
Statement 

Transaction Automatic 

Treat warnings as errors 

Throw exception on database error 0 


FileT ransf erCDT oMsgFlow_Database 


Figure 9-23 Setting the data source 


b. Double-click the Database_DataWarehouse, and enter the ESQL code shown in 
Example 9-2. This ESQL code inserts the transaction record into database. 

Example 9-2 ESQL code 

CREATE DATABASE MODULE Fi 1 eTransferCDToMsgFl ow_Database 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

DECLARE TRANS_ID INT Body .Customer. Transact!* onID; 

DECLARE ACCOUNT INT Body . Customer. AccountNo; 

DECLARE T0_ACC0UNT INT Body .Customer. ToAccountNo; 

DECLARE NAME CHAR Body .Customer. Name; 
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DECLARE TO_IFSC INT Body . Customer. I FSCCode; 

DECLARE T0_BRANCH CHAR Body .Customer. Branch; 

DECLARE AMOUNT INT Body. Customer. Amount; 

DECLARE DATE1 DATE Body . Customer . Date; 

INSERT INTO Database. TRANSL0G( TRANSJD, NAME, ACC0UNT_N0, 

T0_ACC0UNT_N0 , TO_BRANCH_NAME , T0_I FSC_C0DE, AMOUNT, DATE) 

VALUES (TRANS_ID, NAME, ACCOUNT, T0_ACC0UNT, T0_BRANCH, T0_I FSC, AMOUNT, 
DAT El ); 

RETURN TRUE; 

END; 


END MODULE; 


6. Each transaction is validated when the account number is validated, which should be 
10-digits. The validation scans are done at the compute node 
ValidateAndRouteToCoreBankingSystem. 

a. Double-click the compute node, and enter the ESQL code that validates the account 
number shown in Example 9-3. 

Example 9-3 ESQL code 
CREATE COMPUTE MODULE 

Fi 1 eTransferCDToMsgFl ow_Val i dateAndRouteToCoreBanki ngSystem 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

-- CALL CopyMessageHeaders() ; 

CALL CopyEntireMessage() ; 

-- validate account number 

i f(InputRoot. XMLNSC. Customer. AccountNo > 9999999999 OR 
InputRoot .XMLNSC. Customer. AccountNo < 999999999) 

THEN 

THROW USER EXCEPTION MESSAGE 2440 
VALUES ('The customer account number is not valid 1 , 

InputRoot .XMLNSC. Customer. AccountNo) ; 

END IF; 

i f (InputRoot. XMLNSC. Customer. ToAccountNo > 9999999999 OR 
InputRoot .XMLNSC. Customer. ToAccountNo < 999999999) 

THEN 

THROW USER EXCEPTION MESSAGE 2440 
VALUES ('The To account number is not valid', 

InputRoot .XMLNSC. Customer. ToAccountNo) ; 

END IF; 


RETURN TRUE; 
END; 


b. In the Properties view on the Basics tab, select 

FileTransferCDToMsgFlow_ValidateAndRouteToCoreBankingSystem as the 

ESQL module. 

7. Next, the transaction is routed to the core banking system using the TCPIPCIientOutput 
node. To test this scenario, a core banking simulation flow is developed and deployed on 
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the same broker system. More details about simulation flow is provided in the 9.6.4, 
“Creating the simulation flow” on page 469. 

a. Select the TCP/IP Client OutputToCoreBankingSystem node, and open the Basics 
tab in the Properties view. 

If you are using the core banking simulation flow, set the Connection details* value as 
local host: 2225. Otherwise, set the IPAddress:Port number of the core banking 
system, as shown in Figure 2-35. 


I* Problems 51 Deployment Log ZH Properties £3 

51 TCPIP Client Output Node Properties - TCPIP Client OutputToCoreBankingSystem 

Description 


Basic Connection details* <CoreBankjngSystem Host name >: PORT 

Advanced 

e..g.. tcpip, server, com; UU or TCPIPProfiiel 

Request 

Timeout sending data record (seconds)* 60 

Records and Elements 

Validation 

Monitoring 



Figure 9-24 TCP/IP client output node properties (1) 


b. In the Advanced tab, set the Close connection option and Stream Control Options, as 
shown in Figure 9-25. These options are the default. 


[a Problems 51 Deployment Log Properties £3 

§8 TCPIP Client Output Node Properties - TCPIP Client OutputToCoreBankingSystem 



Description 

Basic 

Close connection No 

Advanced 


Stream Control Options 

□ Close output stream after a record has been sent 
Output Stream Modification 
© Leave unchanged 
O Release output stream 

O Reserve output stream (for use by future TCPIP nodes) 

O Reserve output stream (for use by future TCPIP nodes) then release at end of flow 
Input Stream Modification 
® Leave unchanged 
O Release input stream 

O Reserve input stream (for use by future TCPIP nodes) 

O Reserve input stream (for use by future TCPIP nodes) then release at end of flow 

Request 

Records and Elements 

Validation 

Monitoring 



Broadcast Options 

Send to: One Connection 

Selecting Ail A vatlabie Connections wslf cause aii other Advanced options to be ignored 



Figure 9-25 TCP/IP client output node properties (2) 


c. Set the Records and Elements delimiters, as shown in Figure 9-26 on page 465. Here, 
the record delimiter used is Broker System Line End. 
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Delimiters: The DOS and UNIX Line End delimeter type used on the CDInput node 
and the Broker System Line End used here are essentially the same delimiter type. 
The DOS and UNIX Line End delimeter is used with input nodes where the broker is 
receiving the message from an external transport that is setting the delimeter. The 
Broker System Line End is used when the broker sets the end of line character 
based on the operating system it is running on. 


'’ Problems H Deployment Log Properties 

SO TCPIP Client Output Node Properties - TCPIP Client OutputToCoreBankingSystem 

Description 



Basic 

Record definition 

Record is Delimited Data 

Advanced 

Length (bytes) 

0 

Request 



Records and Elements 

Padding byte (hexadecimal) 

20 

Validation 

Delimiter 

Broker System Line End 

Monitoring 

Custom delimiter (hexadecimal) 

00 


Delimiter type 

Postfix 


Figure 9-26 TCP/IP client output node properties (3) 


8. When the core banking system simulation flow sends back a successful response within 
the timeout limit, the TCP/IP Client ReceiveFromCoreBankingSystem node receives it. 

a. Set the basic properties in the TCP/IP Client ReceiveFromCoreBankingSystem, as 
shown in Figure 9-27. Replace <CoreBankingSystem Host Name>:P0RT with the host 
name and port number of the core backing system. In this case, the simulation flow at 
localhost:2225. 


'’ Problems H Deployment Log Properties tZ 

B TCPIP Client Receive Node Properties - TCPIP Client ReceiveFromCoreBankingSystem 



Description 

Basic Connection details* [_<CoreBankjng5ystem Host Name>:PORT 

Advanced 

e.-w- tcpip, server, com/1111 or TCP JPPro fife! 

Request 

Timeout waiting for data record (seconds)* 60 

Result 


Input Message Parsing 

Parser Options 

Records and Elements 

Validation 

Monitoring 


Figure 9-27 TCP/IP client receive properties (1) 


b. Figure 9-28 on page 466 shows the Advanced tab settings for the Close Connection 
and Stream Control options. Set the values as shown. 
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TCPIP Client Receive Node Properties - TCPIP Client ReceiveFromCoreBankingSystem 


Description 

Basic 

Advanced 

Request 

Result 

Input Message Parsing 
Parser Options 
Records and Elements 
Validation 
Monitoring 


Close connection 


No 


Stream Control Options 

1~1 Close input stream after a record has been received 
Input Stream Modification 
@ Leave unchanged 
O Release input stream 

O Reserve input stream (for use by future TCPIP nodes) 

O Reserve input stream (for use by future TCPIP nodes) then release at end of flow 
Output Stream Modification 
@ Leave unchanged 
O Release output stream 

O Reserve output stream (for use by future TCPIP nodes) 

O Reserve output stream (for use by future TCPIP nodes) then release at end of flow 


Figure 9-28 TCP/IP client receive properties (2) 


Figure 9-29 shows Input Message Parsing options. The Message domain is set to 
XMLNSC to parse the XML message sent by the TCPIPServerOutput node. 


f* Problems S! Deployment Log Properties £3 

£ TCPIP Client Receive Node Properties - TCPIP Client ReceiveFromCoreBankingSystem 

Description 



Basic 

Message domain 

XMLNSC : For XML messages (namespace aware, validation, low memory use) 

Advanced 

Message model 


| <Leave blank to use XML schema in a Library or the Application, or select a Messc 

Request 


Result 

Message 
Physical format 

Message coded character set ID* 
Message encoding* 


Input Message Parsing 


Parser Options 
Records and Elements 

Broker System Default 

Validation 

Broker System Determined 

Monitoring 




Figure 9-29 TCP/IP client receive properties (3) 


c. Figure 9-30 on page 467 shows the Records and Elements parsing options. Each 
TCP/IP stream record is delimited by the DOS or UNIX line end. Make sure the 
delimiter is the end of line type across TCPIPCIient Output Node, TCPIPServerlnput 
node, TCPIPServerOutput node, and TCPIPCIientReceive node. 
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S TCPIP Client Receive Node Properties - TCPIP Client ReceiveFromCoreBankingSystem 

Description 



Basic 

Record detection 

Delimited 

Advanced 

Length (bytes) 

0 

Request 

Delimiter 


Result 

D05 or UNIX Line End 

Input Message Parsing 

Custom delimiter (hexadecimal) 

00 

Parser Options 

Delimiter type 

Postfix 

Records and Elements 

Validation 

Monitoring 




Figure 9-30 TCP/IP client receive properties (4) 


9. After the TCPIPCIientReceive node receives the response, a transaction report file name 
is generated by the Compute node SpecifyReplyFileNameUsingTransactionld. The report 
file name is created using the unique Transactionld of each message with the file name as 
Transactionld.txt. 

The ESQL code shown in Example 9-4 helps to generate the file name by populating the 
necessary OutputLocalEnvironment for the CDOutput node that comes next in the flow. 
This ESQL code helps to override the file name set in the CDOutput node File Name 
property. 

a. Double-click the Compute node, and replace the generated code with the code in 
Example 9-4. 

Example 9-4 ESQL code 
CREATE COMPUTE MODULE 

Fi 1 eTransferCDToMsgFl ow_GenerateReplyFi 1 eNameUsi ngTransactionld 
CREATE FUNCTION Main() RETURNS BOOLEAN 
BEGIN 

-- CALL CopyMessageHeaders() ; 

--CALL CopyEntireMessage() ; 

SET OutputLocal Environment. Destination. CD. Name = 

InputRoot.XMLNSC. Customer. TransactionID| | ' .txt' ; 

RETURN TRUE; 

END; 


b. Close the ESQL code. 

c. In the Basic tab of the Properties view, set the Compute node field to 
Local Envi ronment. 

d. Set the ESQL module field to the new module name 

Fi 1 eTransferCDToMsgFl ow_GenerateReplyFi 1 eNameUsi ngTransactionld. 

See Figure 9-31 on page 468. 
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Figure 9-31 Setting the compute mode 


10. The Transactionld.txt file is generated at the location C:\TransctionReply folder on the 
broker system (System-D) using the CDOutput node CD OutputSendReplyFile. Set the 
following properties in the CDOutput Node CD OutputSendReplyFile: 

a. In the Basics tab, replace SNODE with the host name of the Server-D. The Process 
Name is Procl , which the CDOutput node will use to copy the message into a file using 
CD Server. See Figure 9-32. 


I _ Problems H Deployment Log Properties £3 \ 


Description 


Basic 


Request 

Records and Elements 

Validation 

Monitoring 


CD Output Node Properties - CD OutputSendReplyFile 

Settings to transfer files using IBM Sterling Connect: Direct. 
Destination 
SNODE 
Directory 
File name* 


<5ERVER-D HOSTNAME > 


C:\TransactionReply 


report.txt 


For example; test,txt or * txt 


CD Server 

Configurable service 

Options 
Process name 


<Leave blank to use the default configurable service. : 


Procl 


Disposition 


PPL - Replace or create a new file 


Transfer mode Binary transfer (no conversion) 


Figure 9-32 CDOutput node properties (1) 
a. Set the values in Records and Elements, as shown in Figure 9-33. 


CD Output Node Properties - CD OutputSendReplyFile 

Description 

Define how the CDOutput node writes the record derived from the message. 

Basic 

Record definition 
Length (bytes) 

Record is Whole File 

Request 

80 

Records and Elements 


Validation 

Padding byte (hexadecimal) 
Delimiter 

Custom delimiter (hexadecimal) 
Delimiter type 

20 

Monitoring 

Broker System Line End 



Postfix 




Figure 9-33 CDOutput node properties (2) 
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9.6.4 Creating the simulation flow 


A core banking simulation flow, CoreBankingServerSimulation.msgflow, is developed to test 
this scenario, Connect TCPIPServerlnput node to TCPIPServerOutput Node. See 
Figure 9-34. 
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Figure 9-34 Core banking simulation flow 


To create the simulation flow: 

1 . Create a new message flow called CoreBankingServerSimulation in the same application. 

2. Drop a TCPIPServerlnput node and TCPIPServerOutput node to the canvas. 

3. Set the properties in TCPIPServer Input: 

a. Figure 9-35 shows the basic properties. In the Connection details field, specify the port 
to use as the TCP/IP server. In this example, 2225. Leave the Timeout waiting for data 
record field as 60 seconds (its default value). 
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OS TCPIP Server Input Node Properties - TCPIP Server Input 



Description 

Basic Connection details* 2225 

Advanced 

e,y, nn or TCPIPProfifcl 

Input Message Parsing 

Timeout waiting for data record (seconds)* 60 

Parser Options 


Records and Elements 

Retry 

Validation 

Transactions 

Instances 

Monitoring 


Figure 9-35 TCP/IP server input properties (1) 


Figure 9-36 on page 470 shows the values in the Advanced tab for the Close 
Connection and Stream control options. 
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OS TCPIP Server Input Node Properties - TCPIP Server Input 



Description 

Basic 

Close connection No 

Advanced 


Stream Control Options 

1~1 Close input stream after a record has been received 
Input Stream Modification 
© Leave unchanged 

O Reserve input stream (for use by future TCPIP nodes) 

O Reserve input stream (for use by future TCPIP nodes) then release at end of flow 
Output Stream Modification 
@ Leave unchanged 

Release output stream and reset Reply ID 

Input Message Parsing 

Parser Options 

Records and Elements 

Retry 

Validation 

Transactions 

Instances 

Monitoring 



Figure 9-36 TCP/IP server input properties (2) 


b. Figure 9-37 shows the Input Message Parsing options. Set the message domain to 
XMLNSC because the TCP/IP Server gets messages in XML format. 
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(jJ3 TCPIP Server Input Node Properties - TCPIP Server Input 

Description 



Basic 

Message domain 

}<MLNSC : For XML messages (namespace aware, validation, low memory use) 

Advanced 



Message model 

| <Leave blank to use XML schema in a Library or the Application, or select a Me: 

Input Message Parsing 



Parser Options 

Message 
Physical format 


Records and Elements 


Retry 

Validation 

Message coded character set ID* 

Broker System Default 

Transactions 

Message encoding* 

Broker System Determined 

Instances 

Monitoring 




Figure 9-37 TCP/IP server input properties (3) 


c. Figure 9-38 on page 471 shows the Records and Elements properties. The end of 
record delimiter is the DOS or UNIX Line End. This delimiter type (end of line) matches 
the TCPIPCIientOutput node's delimiter (end of line), as shown in Figure Figure 9-26 
on page 465. 
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(jj§ TCPIP Server Input Node Properties - TCPIP Server Input 

Description 



Basic 

Record detection 

Delimited 

Advanced 

Length (bytes) 

0 

Input Message Parsing 

Delimiter 

D05 or UNIX Line End 

Parser Options 



Records and Elements 

Custom delimiter (hexadecimal) 

00 

Retry 

Delimiter type 

Postfix 

Validation 



Transactions 



Instances 



Monitoring 




Figure 9-38 TCP/IP server input properties (4) 


4. Set the properties for the TCPIPServerOutput node: 

a. Figure 9-39 shows the basic properties. Set the Connection details field to 

1 ocal host : 2225, and the Timeout sending the data record field to 60 seconds (the 
default value). 
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@=| TCPIP Server Output Node Properties - TCPIP Server Output 

Description 


Basic Connection details* localhost:2225 

Advanced 

e,y, nn or TCPIPProfiki 

Request 

Timeout sending data record (seconds)* 60 

Records and Elements 

Validation 

Monitoring 



Figure 9-39 TCP/IP server output properties (1) 


b. Figure 9-40 on page 472 shows the Close Connection option and Stream Control 
Options. Set the values as shown in the figure. 


Chapter 9. Integrating file transfer using Sterling Connect:Direct with your message flow 


471 


f* Problems H Deployment Log Properties £3 
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Description 

Basic 

Close connection No 

Advanced 


bLr cam Control Options 

Request 

1 1 Close output stream after a record has been sent 
Output Stream Modification 
® Leave unchanged 
O Release output stream 

O Reserve output stream (for use by future TCPIP nodes) 

O Reserve output stream (for use by future TCPIP nodes) then release at end of flow 
Input Stream Modification 
© Leave unchanged 
©Release input stream 

O Reserve input stream (for use by future TCPIP nodes) 

O Reserve input stream (for use by future TCPIP nodes) then release at end of flow 

Records and Elements 

Validation 

Monitoring 



Broadcast Options 

Send to: One Connection 

Selecting A// Avai/ab/e Connections m// cause a// other Advanced options to be ignored 


Figure 9-40 TCP/IP server output properties (2) 


Figure 9-41 shows Records and Elements delimiter options. The TCPIPServerOutput 
node sets the specified delimiter at the end of the message before sending the reply. 
The delimiter used is Broker System Line End. 
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@=1 TCPIP Server Output Node Properties - TCPIP Server Output 

Description 



Basic 

Record definition 

Record is Delimited Data 

Advanced 

Length (bytes) 

0 

Request 



Records and Elements 

Padding byte (hexadecimal) 

20 

Validation 

Delimiter 

Broker System Line End 

Monitoring 

Custom delimiter (hexadecimal) 

00 


Delimiter type 

Postfix 


Figure 9-4 1 TCP/IP server output properties (3) 


9.6.5 Deploying the message flows and preparing the environment 

To test the message flow: 

1 . Deploy the FileTransferCDToMsgFlow and the CoreBankingServerSimulation flows into 
the message broker execution group. See Figure 9-42 on page 473. 
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Figure 9-42 Deploying flows into the message broker execution group 


2 . Map the C:\EnterpriseDataCenter of System-C to the broker system (System-D). On 
broker System-D, you can see the Transaction Files folder of System-C mapped. 


9.6.6 Sample file transfer data 

Example 9-5 shows sample data for the file (BranchA.txt) to be transferred. Each transaction 
record is delimited by End of line. 

Example 9-5 BranchA.txt 

<Customer><Transacti onID>9129011</Transacti onID><AccountNo>3882919201</AccoiintNo>< 
ToAccountNo>2810380987</ToAccountNo><Name>John</Name><IFSCCode>1239</IFSCCode><Bra 
nch>Bangal ore</Branch><Amount>10000</Amount><Date>2012-03-22</Date></Customer> 
<Customer><Transacti onID>9129012</Transacti onID><AccountNo>1238289128</AccountNo>< 
ToAccountNo>2452991991</ToAccountNo><Name>James</Name><IFSCCode>1234</IFSCCode><Br 
anch>Bangal ore</Branch><Amount>20000</Amount><Date>2012-03-22</Date></Customer> 
<Customer><Transacti onID>9129013</Transacti onID><AccountNo>1238283456</AccountNo>< 
ToAccountNo>2452923456</ToAccountNo><Name>James</Name><IFSCCode>2230</IFSCCode><Br 
anch>Bangal ore</Branch><Amount>50000</Amount><Date>2012-03-22</Date></Customer> 


9.6.7 Testing the message flow 

After the flow is deployed on the broker, the scenario can be tested. 

Transferring the file from BRANCH-A to CENPROC 

Using the CD Requester tool on BRANCH-A, the transaction file 

C:\CDFileTransfer\BranchA.txt is transferred from BRANCH-A to CENPROC. The file will be 
placed in C:\EnterpriseDataCenter\TransactionFiles\BranchA.txt on Server-C u. 

This section provides two methods to start the file transfer. 

Method 1: Using a process file 

This method uses a process file to initiate the file transfer of a file from BRANCH-A: 

1 . Create a file called BRANCH2CENPROC.cdp with the content shown in Example 9-6. 

Example 9-6 BRANCH2CENPROC.cdp 

/*BEGIN_REQUESTER_COMMENTS 

$PNODE$="BRANCH-A" $PN0DE_0S$="Wi ndows" 

$SN0DE$=" CENPROC" $SN0DE_0S$="Wi ndows" 
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$OPTIONS$="WDOS" 

END_REQUESTER_COMMENTS*/ 

PROC PROCESS 
SNODE=CENPROC 

PNODEID=(admi ni strator,password-of-chi 1 dbrach-machi ne) 

SNODEID=(username-of-Server-C-machi ne.password-of-Server-C-machi ne.password-of- 
Server-C-machi ne) 

CPY COPY 
FROM ( 

FI LE="C : \CDFi 1 eT ransfer\BranchA.txt " 

) 

TO ( 

FILE=C:\Enterpri seDataCenter\Transacti on Fi 1 es\BranchA.txt 
DISP=NEW 

) 

PEND 


2. Double-click the file to open it in the CD Requester editor. 

3. In the CDRequester tool, use the process file BRANCH2CENPROC.cdp to initiate the 
transfer. 

4. Change the values of password-of-chi 1 dbranch-machi ne, 
username-of-Server-C-machi ne, and password-of-Server-C-machi ne appropriately in the 
BRANCH2CENPROC.cdp file. 

Method 2: Creating a process 

Alternatively, you can create a process using the CD Requester tool. 

1 . Go to Start ->• All Programs -» Sterling Commerce™ Connect Direct v4.5.01 -» CD 
Requester. 

2. Select File -» New -x Process to create a new process, as shown in Figure 9-43. 



Figure 9-43 Create a new process 
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3. This will launch a new process window as shown in Figure 9-44. Select the Pnode and 
Snode name from the Name drop-downs. 



Figure 9-44 Set process properties 


4. Set the security credentials to connect to the Pnode and Snode, as shown in Figure 9-45 
on page 476. 
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Figure 9-45 Set security credentials 

5. Insert a copy statement to copy the file C:\CDFileTransfer\BranchA.txt from the Pnode on 
Branch-A To C:\EnterpriseDataCenter\TransactionFiles\BranchA.txt to the Snode 
CENPROC. See Figure 9-46 on page 477. 
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Figure 9-46 Set Copy statement 

6. Insert the copy command information, as shown in Figure 9-47 on page 478. 
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Figure 9-47 Set Copy statement parameters 

7. Submit the process to copy the file from source to destination system folders, as shown in 
Figure 9-48 on page 479. 


478 
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Figure 9-48 Submit a process 

8. Click OK to submit the process. 
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Figure 9-49 Submit a process verification 


Verifying that the file was transferred to CENPROC 

The following steps will help you determine if the file transfer was successful: 

1 . Check the statistics in the Process Execution Statistics window to verify whether the copy 
operation was successful: 

a. Select the submit process number executed after submitting the process Procl . 

b. Right-click View Details, as shown in Figure 9-50 on page 481 , to open the Process 
Execution Statistics window. 
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Figure 9-50 View Details 


On successful copy, the following statement will be logged, as shown in Figure 9-51 on 
page 482: 

Copy operation successful 


Chapter 9. Integrating file transfer using Sterling Connect:Direct with your message flow 


481 




Connect: Direct - [Process 1 *] 


pjij File Edit View Node Process Tools Admin Window Help 


| a % m | 

a 

et, {a 

d? go 

b % s m 


_I*J 


] PABHINAV 

y Submit Process... 

Send/Receive File... 
Tj Run Task... 

JT{ Run Job... 
m Initparms... 

Tracing... 

Functional Authorities 
Proxies... 

Netmap 

@ Translation Table... 
sJ5) Stop Node... 
j|fj New Process 
|J] New Work List 
l-£] Process Monitor 
il^l Select Statistics 


j a 


1 5 Nodes 


Files 


Statement 


Label 


Description 


& Process PROC1 

** Copy LABEL 1 

^End 


PROCESS SNODE=CENPROC 

COPY PNODE:C:\CDFileTransf er\BranchA.txt to SNODE:C:\EnterpriseDataCenter\Transa. 
PEND 


Process Execution Statistics 


Process Name: PRO Cl Number: 74 


Submit Node: PABHINAV 



Log Date/Time 

RecID 

Rec Cat 

CCocle 

Msg ID 


a 

4 

28)03/2012 21:09:26 

LSST 

CAPR 

0 




5 

28/03/2012 21:09:26 

CTRC 

CAPR 

0 

SCPA000I 

Copy operation successful. 


6 

28/03/2012 21:09:27 

PRED 

CAPR 

0 

LSMG252I 

A user process has complete 

V 


< 

Details: 


> 


Attribute 

Value 

Message ID 

LCCA01 31 

Message Text 

The submit of the process succeeded. 

Message Data 


Process Name 

PROC1 

Process Number 

74 


Cancel 


Help 


Proc Name 

| Hum | Step | Status | Queue | Bytes 

[ Pnode 

| Snode 

| Func | Submit Date/Time 

Bproci 

74 

PABHINAV 

CENPROC 

28/03/2012 21:09:24 

IJproci 

73 

PABHINAV 

CENPROC 

28/03/2012 21:08:18 

EJproci 

72 

PABHINAV 

CENPROC 

COPY 28/03/2012 21:02:54 


j | | [\ Output Emec Statius f\ Work List Status }\ Activity Log j 



ILl J 


Figure 9-51 Process Execution Statistics window 


Verifying that the message flow processed the file 

After the file is successfully transferred by the CD node from Branch-A system to Server-C 
system, the message broker flow FileTransferCDToMsgFlow on Server-D picks up the file and 
processes each transaction record one by one. It updates the database and generates the 
report files for successful response from core banking system: 

1 . Use the DB2 utilities to verify that the Transaction records are stored in the data 
warehouse table TRANSLOG, as shown in Figure 9-52 on page 483. 
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Figure 9-52 Storing transaction records 

2. Verify that the transaction processing report for each transaction in the file was generated 
in the output folder on the broker system. See Figure 9-53. 



Figure 9-53 Transaction reports 
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Additional material 


This book refers to additional material that can be downloaded from the Internet as described 
in the following sections. 


Locating the Web material 

The Web material associated with this book is available in softcopy on the Internet from the 
IBM Redbooks Web server. Point your Web browser at: 

f tp : / /www . redbooks . i bm.com/ redbooks/SG248020 

Alternatively, you can go to the IBM Redbooks website at: 
ibm.com/redbooks 

Select Additional materials, and open the directory that corresponds with the IBM 
Redbooks form number, SG248020. 


Using the Web material 

The web material is useful as a reference as you follow along with the instructions in this 
book. The files included are not intended to be ready-to-use, but are simply artifacts from the 
projects. 

The additional Web material contained in the archive file provides the following folders: 

► MSMQ folder: Contains the WebSphere Message Broker project interchange file and the 
.NET class code for the scenario in Chapter 4, “Scenario: Bridging WebSphere MQ and 
Microsoft Message Queuing” on page 67. 

► CRM folder: Contains the WebSphere Message Broker project interchange file and the 
.NET class code for the scenario in Chapter 5, “Scenario: Calling Microsoft Dynamics 
CRM from a message flow” on page 109. 
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► WCFService folder: Contains the .NET class code for the scenario in Chapter 6, 
“Scenario: Integration Windows Communication Foundation in message flows - Part 1” on 
page 163. 

► WCFClient folder: Contains the WebSphere Message Broker project interchange file and 
.NET class code for the scenario in Chapter 7, “Scenario: Integrating Windows 
Communication Foundation in message flows - Part 2” on page 273 

► FTE folder: Contains the WebSphere Message Broker project interchange file and the 
.NET class code for the scenario in Chapter 8, “Integrating file transfer with WebSphere 
MQ FTE into the message flow” on page 391 . 

► CD folder: Contains the WebSphere Message Broker project interchange file for the 
scenario in Chapter 9, “Integrating file transfer using Sterling Connect:Direct with your 
message flow” on page 443. 


Downloading and extracting the Web material 

Create a subdirectory (folder) on your workstation, and extract the contents of the Web 
material .zip file into this folder. 
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Related publications 


The publications listed in this section are considered particularly suitable for a more detailed 
discussion of the topics covered in this book. 


IBM Redbooks 

The following IBM Redbooks publications provide additional information about the topics in 
this document. Note that some publications referenced in this list might be available in 
softcopy only: 

► Connecting Your Business Using IBM WebSphere Message Broker V7 as an ESB, 
SG24-7826 

► Patterns: SOA Design Using WebSphere Message Broker and WebSphere ESB, 
SG24-7360 

► WebSphere MQ V7.0 Features and Enhancements, SG24-7583 

You can search for, view, download, or order these documents and other Redbooks, 
Redpapers, Web Docs, draft and additional materials, at the following website: 

ibm.com/redbooks 


Online resources 

These websites are also relevant as further information sources: 

► IBM WebSphere Message Broker Information Center 
http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/index.jsp 

► Express Edition message flow nodes 

http://publib.boulder.ibm.com/infocenter/wmbhelp/v8r0m0/topic/com.ibm.etools.mf 

t.doc/an67720_.htm 

► Using Microsoft .NET in WebSphere Message Broker V8 - DeveloperWorks tutorials 

http://www.ibm.eom/developerworks/views/websphere/l i bra ry view. jsp?search_by=Usi 
ng+Microsoft+.NET+i n+WebSphere+Message+Broker+V8 

► Business Integration - WebSphere MQ SupportPacs 
http://www-l.ibm.com/support/docvi ew.wss?rs=849&ui d=swg27007205 

► IP04: WebSphere Message Broker SupportPacs 

http : //www-01 . i bm.com/support/docvi ew.wss?rs=171&ui d=swg24006518&l oc=en_US&cs=u 
tf-8&lang=en 

► developerWorks articles about WebSphere Message Broker Patterns 

http://www. i bm.com/devel operworks/wi ki s/di spl ay/esbpatterns/ 

http : //www. i bm.com/devel operworks/1 i brary/ws-enterpri seconnecti vi typatterns/i nd 
ex.html 
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http : //www. i bm.com/devel operworks/websphere/1 i brary/techarti cl es/0910_phi 1 1 i i ps 
/0910_phi 11 ips.html 

► Programming Models for Microsoft Dynamics CRM 
http://msdn.mi crosoft .com/en-us/1 i brary/gg327971.aspx 

► Open XML SDK 2.0 for Microsoft Office Download Center 
http://www.mi crosoft.com/downl oad/en/detai 1 s .aspx?i d=5 124 

Help from IBM 

IBM Support and downloads 
ibm.com/support 

IBM Global Services 
ibm.com/servi ces 
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Windows 
Communication 
Foundation services 

Integrate .NET 
applications 

Integrate managed 
file transfer 


IBM WebSphere Message Broker is a lightweight, advanced enterprise 
service bus (ESB) that provides a broad range of integration 
capabilities that enable companies to rapidly integrate internal 
applications and connect to partner applications. Messages from 
business applications can be transformed, augmented and routed to 
other business applications. The types and complexity of the 
integration required will vary by company, application types, and a 
number of other factors. 

Processing logic in WebSphere Message Broker is implemented using 
message flows. Through message flows, messages from business 
applications can be transformed, augmented, and routed to other 
business applications. Message flows are created by connecting nodes 
together. A wide selection of built-in nodes are provided with 
WebSphere Message Broker. These nodes perform tasks that are 
associated with message routing, transformation, and enrichment. 
Message flows are created and tested using the Message Broker 
Toolkit, a sophisticated, easy-to-use programming tool that provides a 
full range of programming aids. 

This IBM Redbooks publication focuses on two specific integration 
requirements that apply to many midmarket companies. The first is the 
ability to use WebSphere Message Broker to integrate Microsoft.NET 
applications into a broader connectivity solution. 

The second is the ability to integrate WebSphere Message Broker with 
file transfer networks, specifically with WebSphere MQ File Transfer 
Edition and IBM Sterling Connect Direct. 
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